statepact 0.1.0__py3-none-any.whl

statepact/__about__.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the distribution version."""
+
+__version__ = "0.1.0"

statepact/__init__.py

@@ -0,0 +1,157 @@
+"""StatePact: transaction management for autonomous AI agents."""
+
+from statepact.__about__ import __version__
+from statepact.concurrency.cas import compare_and_delete, compare_and_swap
+from statepact.concurrency.conflict import Conflict
+from statepact.concurrency.locking import LockManager
+from statepact.concurrency.serializability import SerializationGraphAudit
+from statepact.coordination.fencing import FenceGuard
+from statepact.coordination.lease import LeaseManager
+from statepact.coordination.retry import RetryOutcome, RetryPolicy, run_with_retry
+from statepact.core.context import current_session, require_session
+from statepact.core.exceptions import (
+    AmbiguousResourceError,
+    BackendNotSupportedError,
+    BackendUnavailableError,
+    ConfigurationError,
+    ConflictError,
+    DeadlockError,
+    EffectFailedError,
+    EffectInProgressError,
+    IdempotencyError,
+    IdempotencyMismatchError,
+    KeyNotFoundError,
+    LeaseLostError,
+    LeaseNotAvailableError,
+    LockTimeoutError,
+    ReadWriteConflict,
+    ResourceError,
+    ResourceExistsError,
+    ResourceNotFoundError,
+    ResourceNotInSessionError,
+    RetryExhaustedError,
+    SerializationError,
+    SideEffectError,
+    StaleSnapshotError,
+    StatePactError,
+    StorageError,
+    TransactionAbortedError,
+    TransactionError,
+    TransactionStateError,
+    ValidationError,
+    WriteWriteConflict,
+)
+from statepact.core.idempotency import (
+    EffectRecord,
+    EffectState,
+    EffectStore,
+    IdempotentExecutor,
+    MemoryEffectStore,
+    run_idempotent,
+)
+from statepact.core.interfaces import (
+    ISOLATION_MODES,
+    CommitPlan,
+    CommitResult,
+    IsolationMode,
+    Lease,
+    ReadRecord,
+    ResourceSnapshot,
+    StorageBackend,
+    StoredValue,
+    WriteRecord,
+)
+from statepact.core.manager import (
+    TransactionManager,
+    default_manager,
+    reset_default_manager,
+    set_default_manager,
+)
+from statepact.core.resource import SharedResource
+from statepact.core.session import AgentSession
+from statepact.core.transaction import TransactionState
+from statepact.observability.events import Event, EventBus, EventType
+from statepact.observability.metrics import Metrics
+from statepact.observability.transaction_logs import (
+    TransactionLog,
+    TransactionRecord,
+    TransactionStatus,
+)
+from statepact.storage.memory import MemoryBackend
+
+__all__ = [
+    "ISOLATION_MODES",
+    "AgentSession",
+    "AmbiguousResourceError",
+    "BackendNotSupportedError",
+    "BackendUnavailableError",
+    "CommitPlan",
+    "CommitResult",
+    "ConfigurationError",
+    "Conflict",
+    "ConflictError",
+    "DeadlockError",
+    "EffectFailedError",
+    "EffectInProgressError",
+    "EffectRecord",
+    "EffectState",
+    "EffectStore",
+    "Event",
+    "EventBus",
+    "EventType",
+    "FenceGuard",
+    "IdempotencyError",
+    "IdempotencyMismatchError",
+    "IdempotentExecutor",
+    "IsolationMode",
+    "KeyNotFoundError",
+    "Lease",
+    "LeaseLostError",
+    "LeaseManager",
+    "LeaseNotAvailableError",
+    "LockManager",
+    "LockTimeoutError",
+    "MemoryBackend",
+    "MemoryEffectStore",
+    "Metrics",
+    "ReadRecord",
+    "ReadWriteConflict",
+    "ResourceError",
+    "ResourceExistsError",
+    "ResourceNotFoundError",
+    "ResourceNotInSessionError",
+    "ResourceSnapshot",
+    "RetryExhaustedError",
+    "RetryOutcome",
+    "RetryPolicy",
+    "SerializationError",
+    "SerializationGraphAudit",
+    "SharedResource",
+    "SideEffectError",
+    "StaleSnapshotError",
+    "StatePactError",
+    "StorageBackend",
+    "StorageError",
+    "StoredValue",
+    "TransactionAbortedError",
+    "TransactionError",
+    "TransactionLog",
+    "TransactionManager",
+    "TransactionRecord",
+    "TransactionState",
+    "TransactionStateError",
+    "TransactionStatus",
+    "ValidationError",
+    "WriteRecord",
+    "WriteWriteConflict",
+    "__version__",
+    "compare_and_delete",
+    "compare_and_swap",
+    "current_session",
+    "default_manager",
+    "require_session",
+    "reset_default_manager",
+    "run_idempotent",
+    "run_with_retry",
+    "set_default_manager",
+]

statepact/cli.py

@@ -0,0 +1,82 @@
+"""Command line entry point: ``statepact``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import platform
+import sys
+from collections.abc import Sequence
+
+from statepact.__about__ import __version__
+
+
+def _info() -> int:
+    from statepact.observability.events import EventBus
+    from statepact.storage.memory import MemoryBackend
+
+    backend = MemoryBackend(event_bus=EventBus())
+    payload = {
+        "statepact": __version__,
+        "python": sys.version.split()[0],
+        "platform": platform.platform(),
+        "backend": backend.name,
+        "capabilities": {
+            "mvcc": backend.supports_mvcc,
+            "locking": backend.supports_locking,
+            "leases": backend.supports_leases,
+            "idempotency": backend.supports_idempotency,
+            "durable": backend.durable,
+        },
+    }
+    print(json.dumps(payload, indent=2))
+    return 0
+
+
+async def _smoke() -> int:
+    from statepact import TransactionManager
+
+    manager = TransactionManager()
+    inventory = manager.resource("inventory", {"sku": 1})
+    async with manager.session(agent_id="smoke", resources=[inventory]) as session:
+        stock = await session.read("sku")
+        await session.write("sku", stock - 1)
+        result = await session.commit()
+    remaining = await inventory.read("sku")
+    ok = remaining == 0 and result.committed
+    print(
+        json.dumps(
+            {
+                "ok": ok,
+                "remaining": remaining,
+                "commit_version": result.commit_version,
+                "transaction_id": result.transaction_id,
+            },
+            indent=2,
+        )
+    )
+    await manager.close()
+    return 0 if ok else 1
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="statepact", description="Transaction management for autonomous AI agents"
+    )
+    parser.add_argument("--version", action="version", version=f"statepact {__version__}")
+    subparsers = parser.add_subparsers(dest="command")
+    subparsers.add_parser("info", help="print version, platform and backend capabilities")
+    subparsers.add_parser("smoke", help="run a one-transaction installation smoke test")
+    args = parser.parse_args(argv)
+
+    if args.command == "info":
+        return _info()
+    if args.command == "smoke":
+        return asyncio.run(_smoke())
+    parser.print_help()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

statepact/concurrency/__init__.py

@@ -0,0 +1,22 @@
+"""Concurrency control algorithms: OCC, MVCC, 2PL, conflict detection, CAS."""
+
+from statepact.concurrency.cas import compare_and_swap
+from statepact.concurrency.conflict import Conflict, detect
+from statepact.concurrency.locking import LockManager
+from statepact.concurrency.mvcc import VersionEntry, snapshot_values, visible_entry
+from statepact.concurrency.serializability import (
+    SerializationGraphAudit,
+    TransactionFootprint,
+)
+
+__all__ = [
+    "Conflict",
+    "LockManager",
+    "SerializationGraphAudit",
+    "TransactionFootprint",
+    "VersionEntry",
+    "compare_and_swap",
+    "detect",
+    "snapshot_values",
+    "visible_entry",
+]

statepact/concurrency/cas.py

@@ -0,0 +1,86 @@
+"""Compare-and-swap helper built on the transaction engine.
+
+CAS is the smallest useful primitive for agents: "set this key to a new value only
+if it is still at the version I observed". It is implemented as a one-operation
+transaction so it inherits every backend's atomic validation; it is not a separate
+code path that could silently diverge.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from statepact.core.exceptions import ConflictError
+from statepact.core.interfaces import StorageBackend
+from statepact.core.serde import normalize_value
+from statepact.core.transaction import Transaction, new_transaction_id, utcnow
+from statepact.core.version import UNVERSIONED, Version
+
+
+async def compare_and_swap(
+    backend: StorageBackend,
+    resource: str,
+    key: str,
+    *,
+    expected_version: Version,
+    value: Any,
+    agent_id: str = "cas",
+) -> bool:
+    """Atomically write ``value`` iff ``key`` is at ``expected_version``.
+
+    ``expected_version=0`` means "only if the key does not exist" (insert).
+    Returns ``True`` on success and ``False`` on a version conflict. Backend or
+    configuration errors are never swallowed.
+    """
+
+    normalized = normalize_value(value)
+    transaction = Transaction(
+        id=new_transaction_id(),
+        agent_id=agent_id,
+        isolation="optimistic",
+        resources=(resource,),
+        started_at=utcnow(),
+        fence=None,
+    )
+    transaction.stage_write(resource, key, normalized, expected_version)
+    transaction.record_read(resource, key, expected_version)
+    transaction.mark_committing()
+    try:
+        await backend.commit(transaction.to_plan())
+    except ConflictError:
+        transaction.mark_aborted("compare-and-swap conflict")
+        return False
+    return True
+
+
+async def compare_and_delete(
+    backend: StorageBackend,
+    resource: str,
+    key: str,
+    *,
+    expected_version: Version,
+    agent_id: str = "cas",
+) -> bool:
+    """Delete ``key`` iff it is still at ``expected_version``."""
+
+    transaction = Transaction(
+        id=new_transaction_id(),
+        agent_id=agent_id,
+        isolation="optimistic",
+        resources=(resource,),
+        started_at=utcnow(),
+        fence=None,
+    )
+    transaction.stage_write(resource, key, None, expected_version, op="delete")
+    transaction.record_read(resource, key, expected_version)
+    transaction.mark_committing()
+    try:
+        await backend.commit(transaction.to_plan())
+    except ConflictError:
+        transaction.mark_aborted("compare-and-delete conflict")
+        return False
+    return True
+
+
+def is_absent(version: Version) -> bool:
+    return version == UNVERSIONED

statepact/concurrency/conflict.py

@@ -0,0 +1,121 @@
+"""Conflict classification and detection.
+
+The detector works on ``(resource, key) -> latest version`` maps supplied by the
+backend *inside* its atomic commit section. Keeping it pure lets the same rules
+be exercised by unit and property tests without a backend.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+
+from statepact.core.exceptions import (
+    ConflictClass,
+    ConflictError,
+    ReadWriteConflict,
+    WriteWriteConflict,
+)
+from statepact.core.interfaces import CommitPlan, ReadRecord, WriteRecord
+from statepact.core.version import Version
+
+
+@dataclass(frozen=True, slots=True)
+class Conflict:
+    """A detected version conflict, before it is turned into an exception."""
+
+    kind: ConflictClass
+    transaction_id: str
+    resource: str
+    key: str
+    expected_version: Version
+    actual_version: Version
+    description: str
+
+    def to_exception(self) -> ConflictError:
+        kwargs: dict[str, object] = {
+            "transaction_id": self.transaction_id,
+            "resource": self.resource,
+            "key": self.key,
+            "expected_version": self.expected_version,
+            "actual_version": self.actual_version,
+        }
+        if self.kind == "read_write":
+            return ReadWriteConflict(**kwargs)
+        return WriteWriteConflict(**kwargs)
+
+
+def check_read(record: ReadRecord, latest_version: Version, transaction_id: str) -> Conflict | None:
+    if latest_version == record.version:
+        return None
+    return Conflict(
+        kind="read_write",
+        transaction_id=transaction_id,
+        resource=record.resource,
+        key=record.key,
+        expected_version=record.version,
+        actual_version=latest_version,
+        description=(
+            f"{record.resource}.{record.key} was read at version {record.version} "
+            f"but is now at {latest_version}"
+        ),
+    )
+
+
+def check_write(
+    record: WriteRecord, latest_version: Version, transaction_id: str
+) -> Conflict | None:
+    if latest_version == record.expected_version:
+        return None
+    return Conflict(
+        kind="write_write",
+        transaction_id=transaction_id,
+        resource=record.resource,
+        key=record.key,
+        expected_version=record.expected_version,
+        actual_version=latest_version,
+        description=(
+            f"{record.resource}.{record.key} was staged on version "
+            f"{record.expected_version} but is now at {latest_version}"
+        ),
+    )
+
+
+def detect(
+    plan: CommitPlan,
+    latest: Mapping[tuple[str, str], Version],
+    *,
+    validate_reads: bool,
+    validate_writes: bool,
+) -> Conflict | None:
+    """Return the first conflict in a stable (read order, then write order) scan."""
+
+    if validate_reads:
+        for read in plan.reads:
+            actual = latest.get((read.resource, read.key), 0)
+            conflict = check_read(read, actual, plan.transaction_id)
+            if conflict is not None:
+                return conflict
+    if validate_writes:
+        for write in plan.writes:
+            actual = latest.get((write.resource, write.key), 0)
+            conflict = check_write(write, actual, plan.transaction_id)
+            if conflict is not None:
+                return conflict
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class ValidationOutcome:
+    ok: bool
+    conflict: Conflict | None = None
+
+    def raise_if_conflict(self) -> None:
+        if self.conflict is not None:
+            raise self.conflict.to_exception()
+
+
+def involved_keys(plan: CommitPlan) -> Sequence[tuple[str, str]]:
+    keys = {(read.resource, read.key) for read in plan.reads}
+    keys.update((write.resource, write.key) for write in plan.writes)
+    return tuple(sorted(keys))