marsh-lib 0.3.7__tar.gz → 0.3.8__tar.gz

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: marsh-lib
-Version: 0.3.7
+Version: 0.3.8
 Summary: Lightweight, extensible Python library for building, managing, and executing command workflows.
 Project-URL: Repository, https://github.com/CedricAnover/marsh
 Author-email: Cedric Anover <cedric.anover@hotmail.com>
@@ -584,6 +584,46 @@ The current release line intentionally has several boundaries:
 
 These limitations describe the current implementation; they should not be interpreted as permanent exclusions.
 
+
+## Artifacts and reproducibility (v0.3.8)
+
+v0.3.8 adds provider-independent identity and artifact primitives around the canonical Workflow runtime.
+
+A successful result can expose:
+
+    result.execution_id     # stable semantic execution identity when portable
+    result.attempt_id       # v0.3.7 per-attempt identity
+    result.artifact_refs    # immutable content-addressed artifact references
+    result.provenance       # allow-listed, serializable provenance
+
+Execution identity is derived from canonical workflow semantics. Attempt identity is intentionally separate, so retries do not create a new logical execution identity. Artifact identity is content-derived with SHA-256 and does not depend on where the bytes are stored.
+
+### Opt-in artifact persistence
+
+Use the local content-addressed store when artifact persistence is required:
+
+    from pathlib import Path
+    from marsh import LocalArtifactStore, execute_workflow
+
+    store = LocalArtifactStore(Path(".marsh-artifacts"))
+    results = execute_workflow(workflow, artifact_store=store)
+    result = results["greet"]
+
+    for artifact in result.artifact_refs:
+        assert store.verify(artifact)
+
+The store verifies artifact size and digest on reads and uses temporary files plus atomic finalization for writes. Artifact storage is opt-in; the normal runtime does not require a local artifact directory.
+
+### Cache identity
+
+Caching remains opt-in through the existing policy boundary. Cache keys now use the shared canonical identity primitives rather than a second JSON/hash implementation. A cache hit reuses the cached successful result and does not create another execution attempt.
+
+### Reproducibility boundary
+
+Portable identity data must be deterministic and serializable. Unsupported runtime objects, non-finite numeric values, and non-portable callable definitions are rejected by the identity boundary. Legacy workflows that use non-portable callables remain executable, but they do not receive a portable execution identity.
+
+See docs/artifacts-and-reproducibility.md for the contract, storage layout, provenance rules, and reproducibility guidance.
+
 ## Development
 
 Marsh uses `uv` for dependency and environment management.

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/README.md

@@ -555,6 +555,46 @@ The current release line intentionally has several boundaries:
 
 These limitations describe the current implementation; they should not be interpreted as permanent exclusions.
 
+
+## Artifacts and reproducibility (v0.3.8)
+
+v0.3.8 adds provider-independent identity and artifact primitives around the canonical Workflow runtime.
+
+A successful result can expose:
+
+    result.execution_id     # stable semantic execution identity when portable
+    result.attempt_id       # v0.3.7 per-attempt identity
+    result.artifact_refs    # immutable content-addressed artifact references
+    result.provenance       # allow-listed, serializable provenance
+
+Execution identity is derived from canonical workflow semantics. Attempt identity is intentionally separate, so retries do not create a new logical execution identity. Artifact identity is content-derived with SHA-256 and does not depend on where the bytes are stored.
+
+### Opt-in artifact persistence
+
+Use the local content-addressed store when artifact persistence is required:
+
+    from pathlib import Path
+    from marsh import LocalArtifactStore, execute_workflow
+
+    store = LocalArtifactStore(Path(".marsh-artifacts"))
+    results = execute_workflow(workflow, artifact_store=store)
+    result = results["greet"]
+
+    for artifact in result.artifact_refs:
+        assert store.verify(artifact)
+
+The store verifies artifact size and digest on reads and uses temporary files plus atomic finalization for writes. Artifact storage is opt-in; the normal runtime does not require a local artifact directory.
+
+### Cache identity
+
+Caching remains opt-in through the existing policy boundary. Cache keys now use the shared canonical identity primitives rather than a second JSON/hash implementation. A cache hit reuses the cached successful result and does not create another execution attempt.
+
+### Reproducibility boundary
+
+Portable identity data must be deterministic and serializable. Unsupported runtime objects, non-finite numeric values, and non-portable callable definitions are rejected by the identity boundary. Legacy workflows that use non-portable callables remain executable, but they do not receive a portable execution identity.
+
+See docs/artifacts-and-reproducibility.md for the contract, storage layout, provenance rules, and reproducibility guidance.
+
 ## Development
 
 Marsh uses `uv` for dependency and environment management.

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/docs/api-migration.md

@@ -198,7 +198,28 @@ round_trip = workflow_from_json(payload)
 
 Portable JSON definitions should contain serializable values. Arbitrary Python callables are Python objects and are not general portable JSON definitions.
 
-## 10. Deprecation discipline
+
+## 10. Artifacts, identity, and provenance
+
+v0.3.8 adds identity and artifact fields additively to canonical Result values:
+
+    result.execution_id
+    result.attempt_id
+    result.artifact_refs
+    result.provenance
+
+Existing code that only reads stdout, stderr, status, error, duration, or metadata does not need to change.
+
+For portable workflows, execution_id is deterministic across fresh processes. Retry attempts keep the same execution identity while receiving a distinct attempt identity. Cache hits reuse the successful cached result rather than creating another attempt.
+
+Artifact persistence is opt-in:
+
+    store = LocalArtifactStore(".marsh-artifacts")
+    results = execute_workflow(workflow, artifact_store=store)
+
+Applications that require portability should avoid arbitrary local/lambda callables in workflow definitions. Legacy callable workflows remain supported, but the runtime does not invent a portable execution identity for definitions that cannot cross the canonical serialization boundary.
+
+## 11. Deprecation discipline
 
 The v0.3.x compatibility policy is deliberately conservative:
 
@@ -211,7 +232,7 @@ The v0.3.x compatibility policy is deliberately conservative:
 
 This policy keeps application migrations incremental while the workflow kernel continues to converge.
 
-## 11. Further reading
+## 12. Further reading
 
 - [Workflow Guide](workflow-guide.md) — canonical examples and workflow semantics.
 - [Architecture](architecture.md) — implemented architecture and boundaries.

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/docs/architecture.md

@@ -150,3 +150,67 @@ The attempt lifecycle is: execute -> terminal outcome -> cleanup at most once ->
 Cancellation is a request followed by mechanism-specific stop/terminate/kill and confirmation. A cancellation request is not itself a confirmed CANCELLED result. Timeout cleanup completes before retry eligibility is evaluated.
 
 The policy evaluator is pure and inspectable. Backend differences must not change the policy decision for the same policy, task metadata, outcome, and control history. Runtime-only callbacks such as cleanup functions remain outside the portable IR serialization boundary.
+
+
+## Artifact and identity boundary (v0.3.8)
+
+v0.3.8 extends the existing canonical Workflow IR and runtime rather than introducing a second execution engine.
+
+```mermaid
+flowchart LR
+    W[Workflow / Task] --> C[Canonical IR]
+    C --> E[Execution identity]
+    E --> K[Opt-in cache]
+    W --> R[Existing runtime]
+    R --> A[Attempt identity]
+    R --> O[Result]
+    O --> S[ArtifactStore]
+    S --> AR[ArtifactRef]
+    O --> P[Provenance]
+    E --> P
+    A --> P
+    AR --> P
+```
+
+Plaintext contract:
+
+```text
+Workflow semantics
+    -> canonical UTF-8 representation
+    -> execution identity
+
+Existing scheduler / policy / provider path
+    -> attempt identity
+    -> Result
+
+Result bytes
+    -> SHA-256 content identity
+    -> local ArtifactStore (optional)
+    -> ArtifactRef
+
+Execution identity != attempt identity != artifact identity
+
+Provenance is allow-listed and serializable.
+Storage paths and runtime objects are not semantic identity.
+```
+
+### Identity layers
+
+- Execution identity: semantic fingerprint of a portable workflow execution.
+- Attempt identity: per-attempt runtime identity; retries receive distinct attempt IDs.
+- Artifact identity: SHA-256 of artifact bytes; independent of storage location.
+- Result: semantic outcome that may reference artifacts and provenance.
+
+### ArtifactStore boundary
+
+ArtifactStore is a narrow capability. LocalArtifactStore uses content-addressed paths, manifests, digest/size verification, secure temporary files, and atomic finalization. Remote object stores are not required by the canonical runtime.
+
+### Compatibility boundary
+
+Legacy callable workflows remain executable. When their definitions cannot be represented by the portable canonical IR, runtime identity is unavailable rather than fabricated from process-local object representations.
+
+The runtime accepts an optional ArtifactStore. Without one, existing result streams remain in memory and no artifact directory is required.
+
+### Security boundary
+
+Portable provenance is allow-listed. It must not contain credentials, full environment dumps, arbitrary runtime objects, or storage implementation details. Artifact reads verify content identity and declared size before returning bytes.

marsh_lib-0.3.8/docs/artifacts-and-reproducibility.md

@@ -0,0 +1,130 @@
+# Artifacts and Reproducibility
+
+## Scope
+
+v0.3.8 adds a small provider-independent artifact and identity layer around the existing Workflow runtime.
+
+It does not add a second scheduler, a distributed control plane, a mandatory remote object store, or a new CLI.
+
+## Identity model
+
+Marsh distinguishes four concepts:
+
+- **Execution identity** — a SHA-256 fingerprint of canonical portable workflow semantics.
+- **Attempt identity** — the runtime identity of one execution attempt. Retries create new attempt identities.
+- **Artifact identity** — a SHA-256 digest of artifact bytes. It is independent of storage location.
+- **Result** — the semantic execution outcome, which may reference artifacts and provenance.
+
+The identities must not be conflated. In particular, a retry does not change the logical execution identity, and moving an artifact does not change its artifact identity.
+
+## Canonical execution identity
+
+Portable execution identity is derived from the existing canonical Workflow IR serializer.
+
+The identity boundary uses:
+
+- deterministic UTF-8 JSON;
+- sorted mapping keys and compact separators for generic identity payloads;
+- explicit schema/version markers;
+- rejection of non-finite numeric values;
+- explicit rejection of unsupported runtime objects.
+
+Legacy workflows containing non-portable local callables remain executable. If a workflow cannot cross the canonical serialization boundary, Marsh does not fabricate a supposedly portable identity from process-local object representations.
+
+## Result fields
+
+Canonical Result values may include:
+
+- execution_id;
+- attempt_id;
+- artifact_refs;
+- provenance.
+
+These fields are additive. Existing stdout, stderr, status, error, duration, metadata, and ok behavior remain the primary result semantics.
+
+## ArtifactStore
+
+LocalArtifactStore is content-addressed:
+
+    <root>/
+        objects/
+            <first-two-digest-characters>/
+                <remaining-digest>
+        manifests/
+            <full-digest>.json
+        tmp/
+
+Writes use temporary files and atomic finalization. Existing objects are verified rather than silently accepted as valid. Reads verify both declared size and SHA-256 content identity, and manifest corruption is rejected.
+
+Identical bytes deduplicate to the same content identity.
+
+Artifact persistence is opt-in. The normal runtime does not create an artifact directory unless an ArtifactStore is supplied.
+
+## Provenance
+
+Provenance is an explicit allow-list rather than an environment dump.
+
+The current contract can include:
+
+- schema version;
+- workflow and task identity;
+- execution and attempt identity;
+- parent execution references;
+- operation reference;
+- provider, machine, and policy fingerprints where relevant;
+- input and output artifact references;
+- creation time.
+
+Credentials, full environment variables, arbitrary provider objects, process-local objects, and storage implementation details are not portable provenance.
+
+## Cache semantics
+
+The existing cache boundary remains authoritative.
+
+Cache identity uses the shared canonical identity primitives rather than a separate serialization/hash implementation.
+
+A successful cache hit reuses the cached Result and therefore does not create a new attempt. Corrupt or unverifiable artifact data must not be treated as a valid artifact.
+
+## Reproducibility verification
+
+v0.3.8 tests identity and artifact behavior across:
+
+- fresh Python processes;
+- repeated canonicalization;
+- bounded concurrent artifact writes;
+- artifact reopen/read from another process;
+- manifest corruption;
+- Python 3.10, 3.11, and 3.12 CI;
+- Windows portability CI where the existing workflow permits it.
+
+Reproducibility is a tested property, not an assumption based on implementation intent.
+
+## Compatibility
+
+The canonical runtime keeps the existing scheduler, policy, provider, and execution seams. Artifact storage is optional and is kept outside process-worker state; process workers return normal Results and the parent runtime may materialize artifacts.
+
+This preserves the existing process-scheduler boundary while allowing the same artifact contract to be used by sequential, thread, async, and process execution modes.
+
+## Security considerations
+
+Before release, review:
+
+1. canonicalization for accidental secret inclusion;
+2. provenance allow-list completeness;
+3. artifact path validation and traversal resistance;
+4. digest and size verification;
+5. atomic write behavior under concurrency;
+6. temporary-file cleanup;
+7. cache behavior on corrupt or stale data;
+8. release artifacts and hashes.
+
+## Non-goals
+
+v0.3.8 does not attempt to provide:
+
+- remote object storage;
+- distributed cache invalidation;
+- arbitrary callable serialization;
+- cross-machine execution orchestration;
+- automatic task-to-task dataflow;
+- a general artifact retention/garbage-collection policy.

marsh_lib-0.3.8/docs/release-notes-v0.3.8.md

@@ -0,0 +1,36 @@
+# v0.3.8 — Artifacts & Reproducibility
+
+## Highlights
+
+- Added deterministic canonical execution identity based on the existing Workflow IR.
+- Added SHA-256 content identity for artifacts.
+- Added immutable Artifact and ArtifactRef contracts.
+- Added allow-listed serializable Provenance.
+- Added a local content-addressed ArtifactStore with manifests and integrity verification.
+- Added additive execution/artifact/provenance fields to Result.
+- Added opt-in runtime artifact materialization.
+- Routed cache identity through the shared canonical primitives.
+- Added fresh-process, concurrent, corruption, and cross-process reproducibility coverage.
+- Preserved legacy callable and process-scheduler compatibility.
+
+## Compatibility
+
+Portable execution identity is available when workflow semantics cross the canonical serialization boundary. Legacy non-portable callables remain executable but do not receive a fabricated portable identity.
+
+Artifact persistence is opt-in. Existing workflow execution does not require an artifact directory.
+
+## Verification
+
+Release acceptance requires:
+
+- CircleCI build;
+- CircleCI lint;
+- Python 3.10, 3.11, and 3.12 tests;
+- CircleCI integration;
+- Windows portability checks where configured;
+- package build and artifact inspection;
+- security review;
+- exact artifact hashes;
+- main/develop synchronization.
+
+Upstash Box is intentionally reserved for the final tag/release step and is not used during normal development.

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "marsh-lib"
-version = "0.3.7"
+version = "0.3.8"
 description = "Lightweight, extensible Python library for building, managing, and executing command workflows."
 authors = [{ name = "Cedric Anover", email = "cedric.anover@hotmail.com" }]
 license = { text = "MIT" }

{marsh_lib-0.3.7 → marsh_lib-0.3.8}/src/marsh/core/__init__.py

@@ -43,3 +43,7 @@ from marsh.core.providers import (
 from marsh.core.cache import Cache, CachePolicy, MemoryCache, cache_key_for_task
 from marsh.core.observability import EventType, Observer, RuntimeEvent, emit_event
 from marsh.core.scheduler import AsyncScheduler, ConcurrentScheduler, ExecutorScheduler, ProcessScheduler, SchedulerState, TaskState, ThreadScheduler
+
+from marsh.core.artifacts import Artifact, ArtifactRef, ArtifactStore, Provenance
+from marsh.core.artifact_store import LocalArtifactStore
+from marsh.core.identity import canonical_bytes, content_digest, execution_id

marsh_lib-0.3.8/src/marsh/core/artifact_store.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from marsh.core.artifacts import Artifact, ArtifactRef
+from marsh.core.identity import content_digest
+
+
+class LocalArtifactStore:
+    def __init__(self, root: str | os.PathLike[str]):
+        self.root = Path(root)
+        self.objects = self.root / "objects"
+        self.manifests = self.root / "manifests"
+        self.tmp = self.root / "tmp"
+        self.objects.mkdir(parents=True, exist_ok=True)
+        self.manifests.mkdir(parents=True, exist_ok=True)
+        self.tmp.mkdir(parents=True, exist_ok=True)
+
+    def path_for(self, ref: ArtifactRef) -> Path:
+        digest = ref.digest.removeprefix("sha256:")
+        if len(digest) != 64 or any(
+            char not in "0123456789abcdef" for char in digest
+        ):
+            raise ValueError("invalid artifact digest")
+        return self.objects / digest[:2] / digest[2:]
+
+    def manifest_path_for(self, ref: ArtifactRef) -> Path:
+        return self.manifests / f"{ref.digest.removeprefix('sha256:')}.json"
+
+    def put(
+        self,
+        data: bytes,
+        *,
+        media_type: str = "application/octet-stream",
+    ) -> ArtifactRef:
+        if not isinstance(data, bytes):
+            raise TypeError("artifact data must be bytes")
+
+        digest = content_digest(data)
+        ref = Artifact(digest=digest, size=len(data), media_type=media_type)
+        destination = self.path_for(ref)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+
+        if destination.exists():
+            self.get(ref)
+        else:
+            fd, temp_name = tempfile.mkstemp(prefix="artifact-", dir=self.tmp)
+            try:
+                with os.fdopen(fd, "wb") as handle:
+                    handle.write(data)
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                try:
+                    os.replace(temp_name, destination)
+                except PermissionError:
+                    if not destination.exists():
+                        raise
+                    self.get(ref)
+            finally:
+                try:
+                    os.unlink(temp_name)
+                except FileNotFoundError:
+                    pass
+
+        manifest = {
+            "digest": digest,
+            "size": len(data),
+            "media_type": media_type,
+        }
+        manifest_path = self.manifest_path_for(ref)
+        if manifest_path.exists():
+            existing = json.loads(
+                manifest_path.read_text(encoding="utf-8")
+            )
+            if (
+                existing.get("digest") != digest
+                or existing.get("size") != len(data)
+            ):
+                raise ValueError(
+                    "artifact manifest integrity verification failed"
+                )
+            if existing.get("media_type") != media_type:
+                raise ValueError("artifact metadata conflict")
+        else:
+            fd, temp_name = tempfile.mkstemp(
+                prefix="manifest-", dir=self.tmp, text=True
+            )
+            try:
+                with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                    json.dump(
+                        manifest,
+                        handle,
+                        sort_keys=True,
+                        separators=(",", ":"),
+                    )
+                    handle.write("\n")
+                    handle.flush()
+                    os.fsync(handle.fileno())
+                try:
+                    os.replace(temp_name, manifest_path)
+                except PermissionError:
+                    if not manifest_path.exists():
+                        raise
+            finally:
+                try:
+                    os.unlink(temp_name)
+                except FileNotFoundError:
+                    pass
+
+        return Artifact(
+            digest=digest,
+            size=len(data),
+            media_type=media_type,
+            storage_ref=str(destination),
+            manifest=manifest,
+        )
+
+    def get(self, ref: ArtifactRef) -> bytes:
+        path = self.path_for(ref)
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        data = path.read_bytes()
+        if len(data) != ref.size or content_digest(data) != ref.digest:
+            raise ValueError("artifact integrity verification failed")
+        manifest_path = self.manifest_path_for(ref)
+        if manifest_path.is_file():
+            manifest = json.loads(
+                manifest_path.read_text(encoding="utf-8")
+            )
+            if (
+                manifest.get("digest") != ref.digest
+                or manifest.get("size") != ref.size
+            ):
+                raise ValueError(
+                    "artifact manifest integrity verification failed"
+                )
+        return data
+
+    def exists(self, ref: ArtifactRef) -> bool:
+        return self.path_for(ref).is_file()
+
+    def verify(self, ref: ArtifactRef) -> bool:
+        self.get(ref)
+        return True
+
+    def delete(self, ref: ArtifactRef) -> None:
+        self.path_for(ref).unlink(missing_ok=True)
+        self.manifest_path_for(ref).unlink(missing_ok=True)
+
+    def object_count(self) -> int:
+        return sum(
+            1 for path in self.objects.glob("*/*") if path.is_file()
+        )

marsh_lib-0.3.8/src/marsh/core/artifacts.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol
+
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+@dataclass(frozen=True)
+class Provenance:
+    schema_version: int
+    workflow_id: str
+    workflow_version: str | None = None
+    task_id: str | None = None
+    execution_id: str | None = None
+    attempt_id: str | None = None
+    parent_execution_ids: tuple[str, ...] = ()
+    operation_ref: Mapping[str, Any] | None = None
+    provider_fingerprint: str | None = None
+    machine_fingerprint: str | None = None
+    policy_fingerprint: str | None = None
+    input_artifact_refs: tuple[str, ...] = ()
+    output_artifact_refs: tuple[str, ...] = ()
+    created_at: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.schema_version < 1:
+            raise ValueError("provenance schema_version must be positive")
+        if not self.workflow_id:
+            raise ValueError("provenance workflow_id must be non-empty")
+        object.__setattr__(
+            self, "parent_execution_ids", tuple(self.parent_execution_ids)
+        )
+        object.__setattr__(
+            self, "input_artifact_refs", tuple(self.input_artifact_refs)
+        )
+        object.__setattr__(
+            self, "output_artifact_refs", tuple(self.output_artifact_refs)
+        )
+        if self.operation_ref is not None:
+            object.__setattr__(self, "operation_ref", dict(self.operation_ref))
+
+    def to_dict(self) -> dict[str, Any]:
+        values = {
+            "schema_version": self.schema_version,
+            "workflow_id": self.workflow_id,
+            "workflow_version": self.workflow_version,
+            "task_id": self.task_id,
+            "execution_id": self.execution_id,
+            "attempt_id": self.attempt_id,
+            "parent_execution_ids": list(self.parent_execution_ids),
+            "operation_ref": (
+                dict(self.operation_ref) if self.operation_ref else None
+            ),
+            "provider_fingerprint": self.provider_fingerprint,
+            "machine_fingerprint": self.machine_fingerprint,
+            "policy_fingerprint": self.policy_fingerprint,
+            "input_artifact_refs": list(self.input_artifact_refs),
+            "output_artifact_refs": list(self.output_artifact_refs),
+            "created_at": self.created_at,
+        }
+        return {
+            key: value for key, value in values.items() if value is not None
+        }
+
+
+@dataclass(frozen=True)
+class Artifact:
+    digest: str
+    size: int
+    media_type: str = "application/octet-stream"
+    storage_ref: str | None = None
+    manifest: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not _DIGEST.fullmatch(self.digest):
+            raise ValueError(
+                "artifact digest must be sha256:<64 hex characters>"
+            )
+        if self.size < 0:
+            raise ValueError("artifact size cannot be negative")
+        if not self.media_type:
+            raise ValueError("artifact media_type must be non-empty")
+        object.__setattr__(self, "manifest", dict(self.manifest))
+
+
+ArtifactRef = Artifact
+
+
+class ArtifactStore(Protocol):
+    def put(
+        self,
+        data: bytes,
+        *,
+        media_type: str = "application/octet-stream",
+    ) -> ArtifactRef:
+        ...
+
+    def get(self, ref: ArtifactRef) -> bytes:
+        ...
+
+    def exists(self, ref: ArtifactRef) -> bool:
+        ...
+
+    def verify(self, ref: ArtifactRef) -> bool:
+        ...
+
+    def delete(self, ref: ArtifactRef) -> None:
+        ...