jharness-repository 0.2.2__tar.gz

jharness_repository-0.2.2/.gitignore

@@ -0,0 +1,36 @@
+# OS/editor noise
+.DS_Store
+Thumbs.db
+*.swp
+*.swo
+
+# Local assistant state
+.codex/
+.claude/
+.gemini/
+.aider*
+
+# Python
+__pycache__/
+*.py[cod]
+.python-version
+.venv/
+venv/
+ENV/
+
+# Python tooling caches and reports
+.pytest_cache/
+.ruff_cache/
+.pyright/
+.mypy_cache/
+.coverage
+coverage/
+htmlcov/
+
+# Packaging/build artifacts
+dist/
+build/
+*.egg-info/
+
+# Logs
+*.log

jharness_repository-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JHarness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jharness_repository-0.2.2/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: jharness-repository
+Version: 0.2.2
+Summary: Memory, SQLite, MySQL, and Redis checkpoint repositories for JHarness
+Project-URL: Documentation, https://github.com/Ezio2000/jharness/tree/main/docs
+Project-URL: Repository, https://github.com/Ezio2000/jharness.git
+Author: JHarness contributors
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: jharness-kernel==0.2.2
+Provides-Extra: mysql
+Requires-Dist: pymysql[rsa]>=1.2.0; extra == 'mysql'
+Provides-Extra: redis
+Requires-Dist: redis>=8.0.1; extra == 'redis'
+Description-Content-Type: text/markdown
+
+# jharness-repository
+
+Official in-memory, SQLite, MySQL, and Redis implementations of the JHarness
+`RunRepository` protocol.
+
+```bash
+# Memory and SQLite only
+uv add jharness-repository
+
+# Add exactly the remote drivers the application uses
+uv add "jharness-repository[mysql]"
+uv add "jharness-repository[redis]"
+uv add "jharness-repository[mysql,redis]"
+```
+
+```python
+from jharness.repository import MemoryRunRepository
+```
+
+The base installation has no database-driver dependency. `MemoryRunRepository` needs
+no service, and SQLite uses Python's embedded `sqlite3` module. MySQL and Redis load
+their selected client only when that backend is initialized; there is no fallback or
+compatibility driver. Their services remain supplied by the application, while the
+JHarness development suite exercises them in disposable Docker containers.
+
+The source, contracts, and release process are maintained in the
+[JHarness repository](https://github.com/Ezio2000/jharness).

jharness_repository-0.2.2/README.md

@@ -0,0 +1,27 @@
+# jharness-repository
+
+Official in-memory, SQLite, MySQL, and Redis implementations of the JHarness
+`RunRepository` protocol.
+
+```bash
+# Memory and SQLite only
+uv add jharness-repository
+
+# Add exactly the remote drivers the application uses
+uv add "jharness-repository[mysql]"
+uv add "jharness-repository[redis]"
+uv add "jharness-repository[mysql,redis]"
+```
+
+```python
+from jharness.repository import MemoryRunRepository
+```
+
+The base installation has no database-driver dependency. `MemoryRunRepository` needs
+no service, and SQLite uses Python's embedded `sqlite3` module. MySQL and Redis load
+their selected client only when that backend is initialized; there is no fallback or
+compatibility driver. Their services remain supplied by the application, while the
+JHarness development suite exercises them in disposable Docker containers.
+
+The source, contracts, and release process are maintained in the
+[JHarness repository](https://github.com/Ezio2000/jharness).

jharness_repository-0.2.2/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "jharness-repository"
+version = "0.2.2"
+description = "Memory, SQLite, MySQL, and Redis checkpoint repositories for JHarness"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "JHarness contributors" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = [
+  "jharness-kernel==0.2.2",
+]
+
+[project.optional-dependencies]
+mysql = ["pymysql[rsa]>=1.2.0"]
+redis = ["redis>=8.0.1"]
+
+[project.urls]
+Documentation = "https://github.com/Ezio2000/jharness/tree/main/docs"
+Repository = "https://github.com/Ezio2000/jharness.git"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jharness"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/jharness/repository", "LICENSE", "README.md", "pyproject.toml"]

jharness_repository-0.2.2/src/jharness/repository/__init__.py

@@ -0,0 +1,13 @@
+"""Official checkpoint repository implementations for JHarness."""
+
+from .memory import MemoryRunRepository
+from .mysql import MySQLRunRepository
+from .redis import RedisRunRepository
+from .sqlite import SQLiteRunRepository
+
+__all__ = [
+    "MemoryRunRepository",
+    "MySQLRunRepository",
+    "RedisRunRepository",
+    "SQLiteRunRepository",
+]

jharness_repository-0.2.2/src/jharness/repository/_codec.py

@@ -0,0 +1,72 @@
+"""Canonical checkpoint encoding shared by repository adapters."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import cast
+
+from jharness.kernel import Checkpoint, ProtocolError, RepositoryError
+from jharness.kernel.wire import decode_checkpoint as decode_wire_checkpoint
+from jharness.kernel.wire import encode_checkpoint as encode_wire_checkpoint
+
+
+@dataclass(frozen=True, slots=True)
+class EncodedCheckpoint:
+    """The indexed fields and canonical bytes for one checkpoint."""
+
+    checkpoint_id: str
+    run_id: str
+    revision: int
+    payload: bytes
+    digest: bytes
+
+    @property
+    def expected_revision(self) -> int | None:
+        """Return the head revision required immediately before this checkpoint."""
+        return self.revision - 1 if self.revision else None
+
+
+def encode_checkpoint(checkpoint: Checkpoint) -> EncodedCheckpoint:
+    """Encode a checkpoint into stable JSON bytes and a content fingerprint."""
+    if not isinstance(cast(object, checkpoint), Checkpoint):
+        raise TypeError("checkpoint must be a Checkpoint")
+    checkpoint_id = str.__str__(checkpoint.id)
+    run_id = str.__str__(checkpoint.snapshot.context.run_id)
+    if not checkpoint_id:
+        raise ValueError("checkpoint id must not be empty")
+    if not run_id:
+        raise ValueError("run id must not be empty")
+    payload = json.dumps(
+        encode_wire_checkpoint(checkpoint),
+        allow_nan=False,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return EncodedCheckpoint(
+        checkpoint_id=checkpoint_id,
+        run_id=run_id,
+        revision=checkpoint.snapshot.revision,
+        payload=payload,
+        digest=sha256(payload).digest(),
+    )
+
+
+def decode_checkpoint(payload: bytes) -> Checkpoint:
+    """Decode stored checkpoint bytes, reporting malformed storage uniformly."""
+    if type(payload) is not bytes:
+        raise TypeError("checkpoint payload must be bytes")
+    try:
+        document: object = json.loads(payload)
+        return decode_wire_checkpoint(document)
+    except (
+        OverflowError,
+        RecursionError,
+        UnicodeDecodeError,
+        ProtocolError,
+        TypeError,
+        ValueError,
+    ) as exc:
+        raise RepositoryError("stored checkpoint payload is invalid") from exc

jharness_repository-0.2.2/src/jharness/repository/memory.py

@@ -0,0 +1,70 @@
+"""Process-local, multi-run checkpoint repository."""
+
+from __future__ import annotations
+
+from threading import Lock
+from typing import cast
+
+from jharness.kernel import Checkpoint, RepositoryError, RevisionConflict
+
+from ._codec import EncodedCheckpoint, decode_checkpoint, encode_checkpoint
+
+
+class MemoryRunRepository:
+    """Thread-safe in-memory CAS repository for any number of runs."""
+
+    __slots__ = ("_by_id", "_heads", "_lock")
+
+    def __init__(self) -> None:
+        self._heads: dict[str, EncodedCheckpoint] = {}
+        self._by_id: dict[str, bytes] = {}
+        self._lock = Lock()
+
+    async def commit(self, checkpoint: Checkpoint) -> None:
+        """Atomically advance one run head, or accept an exact prior retry."""
+        encoded = encode_checkpoint(checkpoint)
+        with self._lock:
+            existing_digest = self._by_id.get(encoded.checkpoint_id)
+            if existing_digest is not None:
+                if existing_digest == encoded.digest:
+                    return
+                raise RepositoryError(
+                    f"checkpoint id {encoded.checkpoint_id!r} was reused with new content"
+                )
+
+            head = self._heads.get(encoded.run_id)
+            actual_revision = None if head is None else head.revision
+            if actual_revision != encoded.expected_revision:
+                raise RevisionConflict(
+                    encoded.run_id,
+                    encoded.expected_revision,
+                    actual_revision,
+                )
+
+            previous_head = self._heads.get(encoded.run_id)
+            try:
+                self._by_id[encoded.checkpoint_id] = encoded.digest
+                self._heads[encoded.run_id] = encoded
+            except BaseException:
+                self._by_id.pop(encoded.checkpoint_id, None)
+                if previous_head is None:
+                    self._heads.pop(encoded.run_id, None)
+                else:
+                    self._heads[encoded.run_id] = previous_head
+                raise
+
+    async def get_head(self, run_id: str) -> Checkpoint | None:
+        """Return the authoritative checkpoint for a run, if one exists."""
+        run_id = _validate_run_id(run_id)
+        with self._lock:
+            head = self._heads.get(run_id)
+        return None if head is None else decode_checkpoint(head.payload)
+
+
+def _validate_run_id(run_id: str) -> str:
+    if not isinstance(cast(object, run_id), str):
+        raise TypeError("run_id must be a string")
+    run_id = str.__str__(run_id)
+    if not run_id:
+        raise ValueError("run_id must not be empty")
+    return run_id