roborean-storage-base 0.1.2__tar.gz

roborean_storage_base-0.1.2/.gitignore

@@ -0,0 +1,27 @@
+venv/
+venv-qt5/
+venv-qt6/
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+*.tsbuildinfo
+node_modules/
+.pnpm-store/
+.DS_Store
+.idea/
+.vscode/*.local
+playground/
+.e2e-ai/
+**/test-results/
+**/playwright-report/
+research/
+.roborean/
+.roborean-sql-artifacts/
+*.db

roborean_storage_base-0.1.2/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- `ProjectRepository`, `RunRepository`, and `ArtifactStore` ports with
+  shared storage error types for durable Phase 2 persistence.
+
+### Changed
+
+### Fixed
+
+- Lower inter-package dependency pins to `>=0.1.1` to match lockstep
+  release versions.

roborean_storage_base-0.1.2/PKG-INFO

@@ -0,0 +1,26 @@
+Metadata-Version: 2.4
+Name: roborean-storage-base
+Version: 0.1.2
+Summary: Persistence ports for Roborean projects and runs
+Project-URL: Homepage, https://github.com/TNick/roborean
+Project-URL: Repository, https://github.com/TNick/roborean
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: roborean-spec>=0.1.1
+Provides-Extra: dev
+Requires-Dist: black>=24.0; extra == 'dev'
+Requires-Dist: flake8>=7.0; extra == 'dev'
+Requires-Dist: isort>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# roborean-storage-base
+
+Persistence ports for Roborean projects and durable runs.
+
+```python
+from roborean_storage_base import ProjectRepository, RunRepository
+```
+
+Adapters implement these protocols; the engine never writes files directly
+from `runner.py`.

roborean_storage_base-0.1.2/README.md

@@ -0,0 +1,10 @@
+# roborean-storage-base
+
+Persistence ports for Roborean projects and durable runs.
+
+```python
+from roborean_storage_base import ProjectRepository, RunRepository
+```
+
+Adapters implement these protocols; the engine never writes files directly
+from `runner.py`.

roborean_storage_base-0.1.2/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roborean-storage-base"
+version = "0.1.2"
+description = "Persistence ports for Roborean projects and runs"
+requires-python = ">=3.11"
+license = "MIT"
+readme = "README.md"
+dependencies = [
+  "roborean-spec>=0.1.1",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "black>=24.0", "isort>=5.0", "flake8>=7.0"]
+
+
+[project.urls]
+Homepage = "https://github.com/TNick/roborean"
+Repository = "https://github.com/TNick/roborean"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roborean_storage_base"]

roborean_storage_base-0.1.2/src/roborean_storage_base/__init__.py

@@ -0,0 +1,16 @@
+"""Persistence ports for Roborean projects and durable runs."""
+
+from .errors import ConflictError, IntegrityError, NotFoundError, StorageError
+from .ports import ArtifactStore, ProjectRepository, RunRepository
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ArtifactStore",
+    "ConflictError",
+    "IntegrityError",
+    "NotFoundError",
+    "ProjectRepository",
+    "RunRepository",
+    "StorageError",
+]

roborean_storage_base-0.1.2/src/roborean_storage_base/errors.py

@@ -0,0 +1,17 @@
+"""Shared storage failure types."""
+
+
+class StorageError(Exception):
+    """Base storage failure."""
+
+
+class NotFoundError(StorageError):
+    """Entity missing from the store."""
+
+
+class ConflictError(StorageError):
+    """Idempotency or optimistic-lock conflict."""
+
+
+class IntegrityError(StorageError):
+    """Corrupt or incomplete package."""

roborean_storage_base-0.1.2/src/roborean_storage_base/ports.py

@@ -0,0 +1,57 @@
+"""Repository and artifact store protocols."""
+
+from typing import Protocol
+
+from roborean_spec import Project, RunRecord
+
+
+class ProjectRepository(Protocol):
+    """Load and save portable projects by identifier."""
+
+    def get(self, project_id: str) -> Project:
+        """Return the current revision of a project."""
+
+    def get_revision(self, project_id: str, revision: str) -> Project:
+        """Return a pinned project revision."""
+
+    def save(self, project: Project, *, revision: str | None = None) -> str:
+        """Persist a project and return the revision identifier."""
+
+    def list_ids(self) -> list[str]:
+        """List stored project identifiers."""
+
+    def delete(self, project_id: str) -> None:
+        """Remove a project and its revisions."""
+
+
+class RunRepository(Protocol):
+    """Persist durable run records with idempotency lookup."""
+
+    def get(self, run_id: str) -> RunRecord:
+        """Return one run by identifier."""
+
+    def get_by_idempotency(
+        self, project_id: str, idempotency_key: str
+    ) -> RunRecord | None:
+        """Return an existing run for an idempotency key, if any."""
+
+    def save(self, record: RunRecord) -> None:
+        """Insert a new run record."""
+
+    def update(self, record: RunRecord) -> None:
+        """Replace an existing run record."""
+
+    def list_for_project(
+        self, project_id: str, *, limit: int = 50
+    ) -> list[RunRecord]:
+        """List recent runs for a project, newest first."""
+
+
+class ArtifactStore(Protocol):
+    """Store opaque binary artifacts referenced by runs."""
+
+    def put_bytes(self, key: str, data: bytes, *, content_type: str) -> str:
+        """Store bytes and return the storage key."""
+
+    def get_bytes(self, key: str) -> bytes:
+        """Load previously stored bytes."""

roborean_storage_base-0.1.2/src/roborean_storage_base/types.py

@@ -0,0 +1,5 @@
+"""Re-exports used by storage adapters."""
+
+from roborean_spec import CompiledProject, Project, RunRecord, RunResults
+
+__all__ = ["CompiledProject", "Project", "RunRecord", "RunResults"]

roborean_storage_base-0.1.2/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared fixtures for storage-base tests."""

roborean_storage_base-0.1.2/tests/ports_test.py

@@ -0,0 +1,147 @@
+"""Document expected storage port semantics with an in-memory fake."""
+
+import pytest
+from roborean_spec import (
+    Project,
+    RunRecord,
+    RunRequest,
+    RunStatus,
+    RunTrigger,
+    project_from_dict,
+)
+from roborean_storage_base import ConflictError, NotFoundError
+
+
+class MemoryProjectRepository:
+    """Minimal in-memory project repository for contract tests."""
+
+    def __init__(self) -> None:
+        """Create an empty store."""
+        self._projects: dict[str, Project] = {}
+        self._revisions: dict[tuple[str, str], Project] = {}
+
+    def get(self, project_id: str) -> Project:
+        """Return the current project or raise."""
+        if project_id not in self._projects:
+            raise NotFoundError(project_id)
+        return self._projects[project_id]
+
+    def get_revision(self, project_id: str, revision: str) -> Project:
+        """Return a pinned revision or raise."""
+        key = (project_id, revision)
+        if key not in self._revisions:
+            raise NotFoundError(f"{project_id}@{revision}")
+        return self._revisions[key]
+
+    def save(self, project: Project, *, revision: str | None = None) -> str:
+        """Store the project under a revision."""
+        rev = revision or "1"
+        self._projects[project.id] = project
+        self._revisions[(project.id, rev)] = project
+        return rev
+
+    def list_ids(self) -> list[str]:
+        """List project ids."""
+        return sorted(self._projects)
+
+    def delete(self, project_id: str) -> None:
+        """Delete one project."""
+        self._projects.pop(project_id, None)
+
+
+class MemoryRunRepository:
+    """Minimal in-memory run repository for contract tests."""
+
+    def __init__(self) -> None:
+        """Create an empty store."""
+        self._by_id: dict[str, RunRecord] = {}
+        self._by_key: dict[tuple[str, str], str] = {}
+
+    def get(self, run_id: str) -> RunRecord:
+        """Return one run or raise."""
+        if run_id not in self._by_id:
+            raise NotFoundError(run_id)
+        return self._by_id[run_id]
+
+    def get_by_idempotency(
+        self, project_id: str, idempotency_key: str
+    ) -> RunRecord | None:
+        """Lookup by idempotency key."""
+        run_id = self._by_key.get((project_id, idempotency_key))
+        return None if run_id is None else self._by_id[run_id]
+
+    def save(self, record: RunRecord) -> None:
+        """Insert a run, rejecting duplicate keys."""
+        key = (record.project_id, record.idempotency_key)
+        if key in self._by_key:
+            raise ConflictError("duplicate idempotency key")
+        self._by_id[record.run_id] = record
+        self._by_key[key] = record.run_id
+
+    def update(self, record: RunRecord) -> None:
+        """Replace an existing run."""
+        if record.run_id not in self._by_id:
+            raise NotFoundError(record.run_id)
+        self._by_id[record.run_id] = record
+
+    def list_for_project(
+        self, project_id: str, *, limit: int = 50
+    ) -> list[RunRecord]:
+        """List runs for one project."""
+        items = [
+            item
+            for item in self._by_id.values()
+            if item.project_id == project_id
+        ]
+        return items[:limit]
+
+
+class TestMemoryPorts:
+    """Contract checks for the in-memory fakes."""
+
+    def test_project_missing_raises(self) -> None:
+        """Missing projects raise NotFoundError."""
+        repo = MemoryProjectRepository()
+        with pytest.raises(NotFoundError):
+            repo.get("missing")
+
+    def test_run_idempotency_conflict(self) -> None:
+        """Duplicate idempotency keys conflict on save."""
+        project = project_from_dict(
+            {
+                "schemaVersion": "1.0.0",
+                "id": "p1",
+                "name": "P",
+                "pluginRequirements": [],
+                "workspace": {"variables": []},
+                "bits": [],
+                "documents": [],
+                "templates": [],
+                "metadata": {},
+            }
+        )
+        projects = MemoryProjectRepository()
+        projects.save(project, revision="1")
+        runs = MemoryRunRepository()
+        request = RunRequest(
+            projectId="p1",
+            idempotencyKey="k1",
+            trigger=RunTrigger.TEST,
+        )
+        record = RunRecord(
+            runId="r1",
+            idempotencyKey="k1",
+            projectId="p1",
+            projectRevision="1",
+            compiledDigest="d",
+            status=RunStatus.QUEUED,
+            request=request,
+            attempt=1,
+            engineVersion="0.2.0",
+            pluginVersions={},
+            createdAt="2026-01-01T00:00:00+00:00",
+            requestDigest="abc",
+        )
+        runs.save(record)
+        with pytest.raises(ConflictError):
+            runs.save(record.model_copy(update={"run_id": "r2"}))