weaverstack 0.1.1__py3-none-any.whl

weaver/build_bundle/changes.py

@@ -0,0 +1,186 @@
+"""What a build intends each target to look like afterwards.
+
+A plan says what will *run*. This says what it will *mean*: for each bound
+target, the objects a build adds and the objects it removes. The two are written
+side by side, deliberately, and a test holds them to each other.
+
+**Why declare it rather than derive it.** The effect of an action could be
+inferred — ``prune_schema`` removes a schema, ``write_file`` adds a path — but
+that inference is a model of what executors do, living somewhere no executor can
+correct. It drifts silently. Declaring the effect where the action is rendered
+keeps the two statements next to each other in one function, which is where a
+disagreement is cheapest to notice.
+
+**Why that is not self-certification.** A summary the planner writes about its
+own plan proves nothing on its own. What makes it load-bearing is
+:data:`action_id`: every physical action must be named by exactly one change and
+every change must name a real action, so the two cannot fall out of step without
+a test failing. Adding an artefact type means emitting an action *and* a change;
+forget either and the bijection breaks.
+
+That is also why the identity lives here rather than on the action. A prune
+action deliberately carries no ``resource_node_id`` — a pruned object has no node
+in the repository, which is precisely why it is being pruned — so the thing a
+prune removes has nowhere else to be written down. Here it has somewhere.
+
+Applying these to a :class:`~weaver.build_bundle.prune.TargetInventory` gives the
+state a build is aiming at, which is what lets "a build converges on what the
+source declares" be asserted without installing anything.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable, Mapping
+
+from ..errors import BuildError
+
+#: What a change does to the target.
+ADD = "add"
+REMOVE = "remove"
+EFFECTS = (ADD, REMOVE)
+
+#: What is being changed, in the vocabulary a ``TargetInventory`` holds. Every
+#: name here is one of that class's collections, because the whole point is to
+#: land on it — a kind with nowhere to go would be a change nothing could apply.
+SCHEMA = "schema"
+TABLE = "table"
+VIEW = "view"
+FOLDER = "folder"
+FOLDER_SCHEMA = "folder_schema"
+FILE = "file"
+STORED_PROCEDURE = "stored_procedure"
+OBJECT_KINDS = (SCHEMA, TABLE, VIEW, FOLDER, FOLDER_SCHEMA, FILE, STORED_PROCEDURE)
+
+#: Which inventory collection each kind lives in.
+_COLLECTION = {
+    SCHEMA: "schemas",
+    TABLE: "tables",
+    VIEW: "views",
+    FOLDER: "folders",
+    FOLDER_SCHEMA: "folder_schemas",
+    FILE: "files",
+    STORED_PROCEDURE: "procedures",
+}
+
+
+@dataclass(frozen=True, order=True)
+class TargetChange:
+    """One object a build will add to, or remove from, one target.
+
+    ``name`` is spelled exactly as the inventory spells it — ``DWG.Customer``,
+    ``_/Load/lib/dates.py`` — because it is compared against a real read. A
+    change whose name did not match what a target reports would apply cleanly and
+    describe nothing.
+    """
+
+    effect: str
+    object_kind: str
+    name: str
+    #: The action that brings this about. What makes the summary checkable.
+    action_id: str
+
+    def __post_init__(self) -> None:
+        if self.effect not in EFFECTS:
+            raise BuildError(
+                f"change effect must be one of {', '.join(EFFECTS)}, got {self.effect!r}"
+            )
+        if self.object_kind not in OBJECT_KINDS:
+            raise BuildError(
+                f"change object kind must be one of {', '.join(OBJECT_KINDS)}, "
+                f"got {self.object_kind!r}"
+            )
+        if not self.name or not self.action_id:
+            raise BuildError("a change needs both a name and the action producing it")
+
+    def to_mapping(self) -> dict[str, Any]:
+        return {
+            "effect": self.effect,
+            "object_kind": self.object_kind,
+            "name": self.name,
+            "action_id": self.action_id,
+        }
+
+    @classmethod
+    def from_mapping(cls, mapping: Mapping[str, Any]) -> "TargetChange":
+        return cls(
+            effect=str(mapping["effect"]),
+            object_kind=str(mapping["object_kind"]),
+            name=str(mapping["name"]),
+            action_id=str(mapping["action_id"]),
+        )
+
+
+def added(object_kind: str, name: str, action_id: str) -> TargetChange:
+    return TargetChange(ADD, object_kind, name, action_id)
+
+
+def removed(object_kind: str, name: str, action_id: str) -> TargetChange:
+    return TargetChange(REMOVE, object_kind, name, action_id)
+
+
+def merge(
+    *sections: Mapping[str, Iterable[TargetChange]]
+) -> dict[str, tuple[TargetChange, ...]]:
+    """Fold several target-keyed change sets into one, preserving order."""
+
+    merged: dict[str, list[TargetChange]] = {}
+    for section in sections:
+        for target_id, changes in section.items():
+            merged.setdefault(target_id, []).extend(changes)
+    return {target_id: tuple(changes) for target_id, changes in merged.items()}
+
+
+def apply_to(inventory, changes: Iterable[TargetChange]):
+    """The inventory a target would hold once these changes have been made.
+
+    Pure, and returns a new inventory: the point is to compare a *predicted*
+    state against a declared one, and mutating the input would make the two
+    comparable only once.
+
+    Folder schemas are derived rather than declared where they can be. Adding
+    ``Raw.CustomerCsv`` implies the ``Raw`` area exists, and a target reports it
+    that way; requiring a build to say so separately would be a second thing to
+    keep in step for no gain. Removing a whole area is declared, because that is
+    a decision rather than a consequence.
+    """
+
+    from dataclasses import replace
+
+    collections = {
+        field: list(getattr(inventory, field)) for field in set(_COLLECTION.values())
+    }
+    for change in changes:
+        collection = collections[_COLLECTION[change.object_kind]]
+        folded = {value.casefold() for value in collection}
+        if change.effect == ADD:
+            if change.name.casefold() not in folded:
+                collection.append(change.name)
+        else:
+            collection[:] = [
+                value
+                for value in collection
+                if value.casefold() != change.name.casefold()
+            ]
+            if change.object_kind == FOLDER_SCHEMA:
+                # Removing an area takes what is inside it with it, exactly as
+                # deleting the directory does.
+                prefix = f"{change.name.casefold()}."
+                collections["folders"] = [
+                    value
+                    for value in collections["folders"]
+                    if not value.casefold().startswith(prefix)
+                ]
+
+    implied = {value.split(".", 1)[0] for value in collections["folders"]}
+    for area in sorted(implied):
+        if area.casefold() not in {v.casefold() for v in collections["folder_schemas"]}:
+            collections["folder_schemas"].append(area)
+
+    return replace(
+        inventory,
+        **{
+            field: tuple(sorted(values, key=str.casefold))
+            for field, values in collections.items()
+        },
+    )

weaver/build_bundle/endpoints.py

@@ -0,0 +1,83 @@
+"""The refresh that closes one Lakehouse item's physical work.
+
+A Fabric Lakehouse presents its Delta tables twice: natively to Spark, and
+through a SQL analytics endpoint whose metadata is synchronised behind the
+mutation rather than with it. Everything that reads a Lakehouse *as SQL* reads
+that endpoint — a Warehouse view over another item, a report, a downstream
+shortcut — so a build that created a table and immediately built a dependent view
+over it could and did see the previous shape.
+
+The refresh therefore sits at the item boundary, not in a tail after every item:
+it is the completion barrier for the item that mutated Delta, and it has to be
+behind that item and ahead of anything in a later item layer.
+
+It is planned host-independently, exactly like the rest of the bundle. The
+emulator has no SQL analytics endpoint at all, and the executor says so and skips
+rather than inventing a local equivalent that would keep no promise.
+
+The *placement* is this module's business; the refresh itself belongs to
+:mod:`weaver.build_bundle.executors.sql_endpoint_refresh`. An earlier design put
+one refresh in a global tail after all physical work, which is correct for a
+single item and wrong the moment a second item reads the first: the consumer's
+Warehouse view would be created against endpoint metadata that had not caught up.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..declaration.model import WeaverItemId
+from .models import CREATE_ALIAS, REFRESH_SQL_ENDPOINT, BuildAction, BuildBatch
+from .physical import DELTA_MUTATING_KINDS
+from .stages import REFRESH, PlannedStage
+from .targets import BoundTarget, WAREHOUSE_TARGET
+
+#: Everything that leaves a Lakehouse's endpoint metadata stale. Alias creation
+#: is here because a OneLake shortcut *is* a new table in the destination.
+_MUTATING = DELTA_MUTATING_KINDS | {CREATE_ALIAS}
+
+
+def item_refresh_stage(
+    stages: Iterable[PlannedStage],
+    *,
+    item: WeaverItemId,
+    target: BoundTarget,
+) -> PlannedStage | None:
+    """One refresh for this item, when its planned work mutated Delta.
+
+    A Warehouse item has no endpoint of its own to refresh — it *is* reached over
+    SQL — and an item whose only work was a folder or a schema has changed
+    nothing the endpoint describes.
+    """
+
+    if target.kind == WAREHOUSE_TARGET:
+        return None
+    if not any(
+        action.kind in _MUTATING
+        for stage in stages
+        for batch in stage.batches
+        for action in batch.actions
+    ):
+        return None
+    slug = str(item).replace("/", "--").replace(" ", "-")
+    return PlannedStage(
+        phase=REFRESH,
+        slug="refresh-endpoints",
+        description="refresh mutated Lakehouse SQL endpoints",
+        batches=(
+            BuildBatch(
+                id=f"refresh-endpoint-{slug}",
+                target_id=target.id,
+                actions=(
+                    BuildAction(
+                        id=f"refresh-sql-endpoint-{slug}",
+                        kind=REFRESH_SQL_ENDPOINT,
+                        resource_node_id=None,
+                        executor="sql_endpoint_refresh",
+                        payload=None,
+                        payload_sha256=None,
+                    ),
+                ),
+            ),
+        ),
+    )

weaver/build_bundle/executors/__init__.py

@@ -0,0 +1,69 @@
+"""Executor dispatch for build actions.
+
+``spark_sql`` runs one create or frozen ``DROP``; ``spark_sql_batch`` runs an
+ordered catalogue payload as one reported action. ``spark_schema`` makes one
+schema, ``spark_table`` completes a table whose shape only the session knows,
+and ``folder`` makes or removes a directory. ``tsql`` is the Warehouse SQL path.
+``alias`` points one Lakehouse name at another item's object, and ``sql_endpoint``
+syncs a Lakehouse's SQL analytics endpoint.
+
+``load_file`` closes an item: it writes one file of the deployed runtime tree, or
+removes one the source has stopped claiming. Generated load procedures need no
+executor of their own — a create-or-alter is T-SQL, and ``tsql`` runs the payload
+it is given without inspecting what the payload builds.
+
+There is no prune executor — a build freezes its drops as payloads, so the
+installer never enumerates the target.
+
+Every Spark executor addresses the destination its batch names, and none of them
+relies on what the session is attached to.
+"""
+
+from __future__ import annotations
+
+from .alias import AliasExecutor
+from .base import ActionExecutor, InstallationContext, ResolvedTarget, SkippedExecution
+from .folder import FolderExecutor
+from .load_file import LoadFileExecutor
+from .spark_schema import SparkSchemaExecutor
+from .spark_sql import SparkSqlExecutor
+from .spark_sql_batch import SparkSqlBatchExecutor
+from .spark_table import SparkTableExecutor
+from .sql_endpoint_refresh import SqlEndpointRefreshExecutor
+from .tsql import TSqlBatchExecutor, TSqlExecutor
+
+
+def default_executors() -> dict[str, ActionExecutor]:
+    """The executor registry, by name — the names actions carry."""
+
+    return {
+        SparkSqlExecutor.name: SparkSqlExecutor(),
+        SparkSqlBatchExecutor.name: SparkSqlBatchExecutor(),
+        SparkSchemaExecutor.name: SparkSchemaExecutor(),
+        SparkTableExecutor.name: SparkTableExecutor(),
+        FolderExecutor.name: FolderExecutor(),
+        LoadFileExecutor.name: LoadFileExecutor(),
+        TSqlExecutor.name: TSqlExecutor(),
+        TSqlBatchExecutor.name: TSqlBatchExecutor(),
+        AliasExecutor.name: AliasExecutor(),
+        SqlEndpointRefreshExecutor.name: SqlEndpointRefreshExecutor(),
+    }
+
+
+__all__ = [
+    "ActionExecutor",
+    "InstallationContext",
+    "ResolvedTarget",
+    "AliasExecutor",
+    "SkippedExecution",
+    "SparkSchemaExecutor",
+    "SparkSqlExecutor",
+    "SparkSqlBatchExecutor",
+    "SparkTableExecutor",
+    "SqlEndpointRefreshExecutor",
+    "FolderExecutor",
+    "LoadFileExecutor",
+    "TSqlExecutor",
+    "TSqlBatchExecutor",
+    "default_executors",
+]

weaver/build_bundle/executors/alias.py

@@ -0,0 +1,202 @@
+"""Materialising one Lakehouse alias — a pointer, in whatever form the host has.
+
+The payload names two addresses and nothing else: this item's ``Schema.Object``,
+and the object in another item it stands for. Both are resolved through the
+environment, the same way every other action's destination is, so the bundle
+carries no path from the machine that wrote it.
+
+The *form* the pointer takes is transport:
+
+``Fabric``
+    a OneLake shortcut in the destination Lakehouse, created through the
+    workspace's own API.
+``the local emulator``
+    a filesystem link beside the destination's other tables, which is what makes
+    the emulator's ``Tables/`` area keep mirroring what a shortcut looks like in
+    OneLake — plus the catalogue registration Fabric performs for itself, because
+    a link no statement could name would not be an alias at all.
+
+That is the same split :mod:`weaver.build_bundle.executors.spark_schema`
+documents: which alias, over what, is settled and in the manifest; how a name is
+made to point somewhere is the environment's business. An alias holds no data, so
+an existing one is replaced rather than treated as an unexpected collision — a
+build has to be able to run twice.
+
+**The action is not finished until the alias can be read.** Fabric creates a
+shortcut synchronously and *discovers* it asynchronously, so the API call
+returning is not the same thing as the alias existing: for a few seconds the
+Lakehouse reports the name as "neither a view nor a table". An action that
+reported success there would make the barrier the plan puts around it a lie, and
+the failure would surface in the next item's DDL — which is exactly where it did
+surface, before this waited.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from ...errors import InstallError
+from ...targets import DeltaTarget, FolderTarget
+from ..models import BuildAction
+from .base import InstallationContext, ResolvedTarget
+from .spark_case import exact_identifier_case
+
+FILES_AREA = "Files"
+
+#: How long a freshly created shortcut may take to become addressable, and how
+#: often to ask. Discovery normally takes seconds; the bound exists so a
+#: never-appearing alias fails naming itself rather than as an obscure error in
+#: whatever statement reads it next.
+ADDRESSABLE_TIMEOUT = 300.0
+ADDRESSABLE_POLL_INTERVAL = 5.0
+
+
+class AliasExecutor:
+    name = "alias"
+
+    def execute(
+        self,
+        action: BuildAction,
+        payload: bytes | None,
+        context: InstallationContext,
+    ) -> dict[str, Any] | None:
+        if payload is None:
+            raise InstallError(f"alias action {action.id!r} has no payload")
+        frozen = json.loads(payload.decode("utf-8"))["aliases"]
+        if not frozen:
+            return {"aliases": []}
+
+        shortcut = getattr(context.resolver, "create_onelake_shortcut", None)
+        link = getattr(context.store, "link", None)
+        if shortcut is None and link is None:
+            raise InstallError(
+                f"alias action {action.id!r} cannot be materialised here: this "
+                "environment offers neither a OneLake shortcut nor a store link"
+            )
+
+        made = []
+        for each in frozen:
+            source = context.resolved(each["source_target_id"])
+            if shortcut is not None:
+                made.append(self._shortcut(shortcut, each, context, source))
+            else:
+                made.append(self._link(link, each, context, source))
+
+        details: dict[str, Any] = {"aliases": made}
+        # Every shortcut is created before anything waits, so the cost is one
+        # discovery window rather than one per alias.
+        if shortcut is not None and context.spark is not None:
+            waited = self._await_addressable(context, frozen)
+            if waited is not None:
+                details["addressable_after_seconds"] = waited
+        return details
+
+    def _shortcut(self, shortcut, frozen: dict, context, source) -> dict:
+        made = shortcut(
+            context.target.lakehouse,
+            path=f"{frozen['area']}/{frozen['schema']}",
+            name=frozen["object"],
+            source=source.lakehouse,
+            source_path=(
+                f"{frozen['source_area']}/{frozen['source_schema']}"
+                f"/{frozen['source_object']}"
+            ),
+        )
+        return {"alias": frozen["alias"], "source": frozen["source"], **(made or {})}
+
+    def _link(self, link, frozen: dict, context, source) -> dict:
+        destination = _location(context.target, frozen, context, source=False)
+        producer = _location(source, frozen, context, source=True)
+        if not context.store.exists(producer):
+            raise InstallError(
+                f"alias {frozen['alias']} has no source to point at: "
+                f"{producer.value} does not exist"
+            )
+        if context.store.exists(destination):
+            context.store.delete(destination, recursive=True)
+        link(producer, destination)
+        made = {
+            "alias": frozen["alias"],
+            "source": frozen["source"],
+            "linked": destination.value,
+            "to": producer.value,
+        }
+        if frozen["area"] != FILES_AREA and context.spark is not None:
+            # Fabric discovers a shortcut under Tables/ and the table appears in
+            # the catalogue. Local Spark discovers nothing, so the emulator names
+            # it — otherwise the link would exist and no statement could reach it.
+            catalogue = context.catalogue
+            with exact_identifier_case(
+                context.spark,
+                enabled=catalogue.destination.preserve_table_identifier_case,
+            ):
+                made["registered"] = catalogue.register_external_table(
+                    frozen["schema"], frozen["object"], destination.value
+                )
+        return made
+
+    def _await_addressable(self, context: InstallationContext, frozen: list) -> float | None:
+        """Wait until every table alias just created can actually be read.
+
+        The probe is a read, not a catalogue lookup, because the catalogue is the
+        thing that is briefly wrong: Fabric reports the shortcut's metadata
+        location while still refusing it as a relation. Only a read that succeeds
+        proves the alias is usable, and a read is what the next action does.
+
+        All of them are waited on together, so several aliases cost one discovery
+        window instead of one each.
+        """
+
+        catalogue = context.catalogue
+        pending = {
+            each["alias"]: catalogue.qualify(each["schema"], each["object"])
+            for each in frozen
+            if each["area"] != FILES_AREA
+        }
+        if not pending:
+            return None
+
+        started = time.monotonic()
+        deadline = started + ADDRESSABLE_TIMEOUT
+        failure: Exception | None = None
+        while pending:
+            for alias, qualified in list(pending.items()):
+                try:
+                    with exact_identifier_case(
+                        context.spark,
+                        enabled=catalogue.destination.preserve_table_identifier_case,
+                    ):
+                        context.spark.sql(f"SELECT * FROM {qualified} LIMIT 0").collect()
+                    del pending[alias]
+                except Exception as exc:  # not discovered yet — or never will be
+                    failure = exc
+            if not pending:
+                break
+            if time.monotonic() >= deadline:
+                raise InstallError(
+                    f"alias(es) {', '.join(sorted(pending))} were created but did "
+                    f"not become readable within {int(ADDRESSABLE_TIMEOUT)}s: {failure}"
+                ) from failure
+            time.sleep(ADDRESSABLE_POLL_INTERVAL)
+        return round(time.monotonic() - started, 1)
+
+
+def _location(
+    target: ResolvedTarget,
+    frozen: dict,
+    context: InstallationContext,
+    *,
+    source: bool,
+):
+    area = frozen["source_area"] if source else frozen["area"]
+    schema = frozen["source_schema"] if source else frozen["schema"]
+    name = frozen["source_object"] if source else frozen["object"]
+    if area == FILES_AREA:
+        return context.resolver.folder_object(
+            FolderTarget(lakehouse=target.lakehouse), schema, name
+        )
+    return context.resolver.delta_table(
+        DeltaTarget(lakehouse=target.lakehouse), schema, name
+    )

weaver/build_bundle/executors/base.py

@@ -0,0 +1,132 @@
+"""The executor seam — dispatch only, no planning.
+
+An executor runs one action's payload against one resolved target and returns
+optional structured details, or raises. It never reads the repository, resolves
+a dependency or selects a target: those decisions are all in the bundle already.
+The installer owns timing, status and reporting; an executor owns the work.
+
+The context carries runtime services — a Spark session, the resolver and store —
+plus the one target the current batch is bound to. It carries no planning input,
+and no way back to the repository: everything an action needs is its payload.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol
+
+from ...errors import InstallError
+from ...locations import LakehouseSparkLocation
+from ...spark import SparkCatalogue, SparkDestination
+from ...store import Store
+from ...targets import ItemRef
+from ..models import BuildAction
+from ..targets import BoundTarget
+
+
+@dataclass(frozen=True)
+class ResolvedTarget:
+    """A manifest target resolved to what the executor addresses.
+
+    ``lakehouse`` is the logical item the bundle named. The other two are that
+    item resolved into the two things Spark needs to reach it, and they are two
+    because Fabric answers them separately:
+
+    ``location``
+        the physical roots — where the bytes are. An ``abfss://`` URL on Fabric, a
+        directory locally.
+    ``destination``
+        the catalogue name — what a statement calls it. Fabric's four-part
+        ``workspace.lakehouse.schema.object``; locally the folded database name.
+
+    Both are needed, and neither substitutes for the other: a folder is created at
+    a path and has no catalogue name, while a view exists only as a name and has no
+    path of its own.
+
+    Resolution happens here, once per target, rather than in each executor. An
+    executor that derived either for itself would be re-deciding where an action
+    lands, which is a planning decision it is not allowed to make. It is also what
+    lets one session build several destinations, and write the catalogue to a
+    different one again, without ever switching what the session is attached to.
+
+    Both are None for a Warehouse target, which is reached over TDS and has
+    neither.
+    """
+
+    bound: BoundTarget
+    lakehouse: ItemRef
+    location: LakehouseSparkLocation | None = None
+    destination: SparkDestination | None = None
+
+
+@dataclass(frozen=True)
+class InstallationContext:
+    """Runtime services and the one target the current batch is bound to.
+
+    ``spark`` runs Lakehouse work; ``sql`` runs Warehouse (T-SQL) work. A batch
+    names one target, so only the capability its actions need has to be present.
+
+    ``targets`` holds every target the plan declared, already resolved. It exists
+    for the one action that legitimately spans two of them — an alias, which
+    points a name in ``target`` at an object in another — and it carries resolved
+    targets rather than ids so that a second destination is addressed exactly as
+    the batch's own is, and never derived by an executor.
+    """
+
+    spark: Any
+    resolver: Any
+    store: Store
+    target: ResolvedTarget
+    sql: Any = None
+    targets: Mapping[str, ResolvedTarget] = field(default_factory=dict)
+    #: This installation's publication instant, resolved into ``{{epoch}}``. One
+    #: value for the whole run, so every Registry row a build writes carries the
+    #: same one and two rows can be ordered against each other. It is not a
+    #: destination's business, which is why it lives here rather than being
+    #: resolved with the object tokens.
+    epoch: str | None = None
+
+    def resolved(self, target_id: str) -> ResolvedTarget:
+        """Another target this plan declared, by the id an action names."""
+
+        found = self.targets.get(target_id)
+        if found is None:
+            raise InstallError(
+                f"action names target {target_id!r}, which this plan does not declare"
+            )
+        return found
+
+    @property
+    def catalogue(self) -> SparkCatalogue:
+        """Catalogue operations against *this batch's* destination.
+
+        Built per access rather than stored, so the context stays a frozen record
+        of what was resolved. Failing here — rather than falling back to the
+        session's own catalogue — is the point: an action with nowhere to go must
+        stop, not land somewhere plausible (how-does-build-work §4).
+        """
+
+        if self.target.destination is None:
+            raise InstallError(
+                f"target {self.target.bound.id!r} resolved to no Spark destination, "
+                "so a statement naming an object has nowhere to run"
+            )
+        return SparkCatalogue(self.spark, self.target.destination)
+
+
+@dataclass(frozen=True)
+class SkippedExecution:
+    """An executor's explicit, non-failing decision not to run on this host."""
+
+    details: dict[str, Any] | None = None
+
+
+class ActionExecutor(Protocol):
+    name: str
+
+    def execute(
+        self,
+        action: BuildAction,
+        payload: bytes | None,
+        context: InstallationContext,
+    ) -> dict[str, Any] | SkippedExecution | None: ...