deltav 0.0.0__py3-none-any.whl

deltav/__init__.py

@@ -0,0 +1,53 @@
+from .core import (
+    Breach,
+    Budget,
+    BudgetStore,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    Usage,
+    UsageMap,
+    canonicalize,
+    check,
+    check_stack,
+    empty_usage,
+    release,
+    release_stack,
+    reserve,
+    reserve_stack,
+    settle,
+    settle_stack,
+)
+from .store_convex import ConvexBudgetStore, create_budget_operations
+from .store_local import InMemoryBudgetStore
+from .store_postgres import DriverBudgetStore, PostgresBudgetStore
+from .store_remote import RemoteBudgetStore
+
+__all__ = [
+    "Breach",
+    "Budget",
+    "BudgetStore",
+    "ConvexBudgetStore",
+    "Decision",
+    "DriverBudgetStore",
+    "InMemoryBudgetStore",
+    "PostgresBudgetStore",
+    "RemoteBudgetStore",
+    "Reservation",
+    "Spend",
+    "SpendRequest",
+    "Usage",
+    "UsageMap",
+    "canonicalize",
+    "check",
+    "check_stack",
+    "create_budget_operations",
+    "empty_usage",
+    "release",
+    "release_stack",
+    "reserve",
+    "reserve_stack",
+    "settle",
+    "settle_stack",
+]

deltav/core.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Protocol
+
+Spend = dict[str, float]
+
+
+@dataclass(frozen=True)
+class Budget:
+    id: str
+    layer: str
+    limits: dict[str, float]
+
+
+@dataclass(frozen=True)
+class Usage:
+    cumulative: Spend = field(default_factory=dict)
+    concurrent: Spend = field(default_factory=dict)
+    peak: Spend = field(default_factory=dict)
+    reserved: Spend = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class SpendRequest:
+    estimate: Spend
+    run_id: str | None = None
+
+
+@dataclass(frozen=True)
+class Reservation:
+    id: str
+    estimate: Spend
+
+
+@dataclass(frozen=True)
+class Breach:
+    budget_id: str
+    layer: str
+    dimension: str
+    limit: float
+    would_be: float
+
+
+@dataclass(frozen=True)
+class Decision:
+    ok: bool
+    reservation: Reservation | None = None
+    breach: Breach | None = None
+
+
+UsageMap = dict[str, Usage]
+_next_reservation = 1
+
+
+class BudgetStore(Protocol):
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]: ...
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision: ...
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None: ...
+    async def release(self, stack_id: str, reservation: Reservation) -> None: ...
+    async def snapshot(self, stack_id: str) -> UsageMap: ...
+
+
+def empty_usage() -> Usage:
+    return Usage()
+
+
+def check(budget: Budget, usage: Usage, req: SpendRequest) -> Decision:
+    for dimension, amount in req.estimate.items():
+        limit = budget.limits.get(dimension)
+        if limit is None:
+            continue
+        if amount < 0:
+            return Decision(
+                ok=False,
+                breach=Breach(budget.id, budget.layer, dimension, 0, amount),
+            )
+        would_be = usage.cumulative.get(dimension, 0) + usage.reserved.get(dimension, 0) + amount
+        if would_be > limit:
+            return Decision(
+                ok=False,
+                breach=Breach(budget.id, budget.layer, dimension, limit, would_be),
+            )
+    return Decision(ok=True, reservation=_reservation(req.estimate))
+
+
+def check_stack(stack: list[Budget], usages: UsageMap, req: SpendRequest) -> Decision:
+    reservation: Reservation | None = None
+    for budget in stack:
+        decision = check(budget, usages.get(budget.id, empty_usage()), req)
+        if not decision.ok:
+            return decision
+        reservation = decision.reservation
+    return Decision(ok=True, reservation=reservation or _reservation(req.estimate))
+
+
+def reserve(usage: Usage, req: SpendRequest) -> Usage:
+    return Usage(
+        cumulative=dict(usage.cumulative),
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, req.estimate),
+    )
+
+
+def settle(usage: Usage, reservation: Reservation, actual: Spend) -> Usage:
+    cumulative = dict(usage.cumulative)
+    for dimension, amount in actual.items():
+        cumulative[dimension] = cumulative.get(dimension, 0) + amount
+    return Usage(
+        cumulative=cumulative,
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, {k: -v for k, v in reservation.estimate.items()}),
+    )
+
+
+def release(usage: Usage, reservation: Reservation) -> Usage:
+    return Usage(
+        cumulative=dict(usage.cumulative),
+        concurrent=dict(usage.concurrent),
+        peak=dict(usage.peak),
+        reserved=_add_delta(usage.reserved, {k: -v for k, v in reservation.estimate.items()}),
+    )
+
+
+def reserve_stack(stack: list[Budget], usages: UsageMap, req: SpendRequest) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = reserve(next_usages.get(budget.id, empty_usage()), req)
+    return next_usages
+
+
+def settle_stack(
+    stack: list[Budget], usages: UsageMap, reservation: Reservation, actual: Spend
+) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = settle(
+            next_usages.get(budget.id, empty_usage()), reservation, actual
+        )
+    return next_usages
+
+
+def release_stack(stack: list[Budget], usages: UsageMap, reservation: Reservation) -> UsageMap:
+    next_usages = dict(usages)
+    for budget in stack:
+        next_usages[budget.id] = release(next_usages.get(budget.id, empty_usage()), reservation)
+    return next_usages
+
+
+def canonicalize(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), default=_json_default)
+
+
+def _reservation(estimate: Spend) -> Reservation:
+    global _next_reservation
+    reservation = Reservation(id=f"reservation_{_next_reservation}", estimate=dict(estimate))
+    _next_reservation += 1
+    return reservation
+
+
+def _add_delta(values: Spend, delta: Spend) -> Spend:
+    out = dict(values)
+    for dimension, amount in delta.items():
+        value = out.get(dimension, 0) + amount
+        if value == 0:
+            out.pop(dimension, None)
+        else:
+            out[dimension] = value
+    return out
+
+
+def _json_default(value: object) -> object:
+    if hasattr(value, "__dict__"):
+        return value.__dict__
+    raise TypeError(f"Cannot serialize {type(value)!r}")

deltav/store_convex.py

@@ -0,0 +1,276 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from dockbay import (
+    ConvexOperationContext,
+    ConvexOperationDriver,
+    ConvexStoreOperation,
+    JsonValue,
+)
+
+from .core import (
+    Budget,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    Usage,
+    UsageMap,
+    check_stack,
+    release_stack,
+    reserve_stack,
+    settle_stack,
+)
+
+LOAD = "budget.load"
+TRY_RESERVE = "budget.tryReserve"
+SETTLE = "budget.settle"
+RELEASE = "budget.release"
+SNAPSHOT = "budget.snapshot"
+
+InitialState = dict[str, tuple[list[Budget], UsageMap]]
+_StackState = dict[str, Any]
+
+
+class ConvexBudgetStore:
+    def __init__(
+        self,
+        driver: ConvexOperationDriver,
+        *,
+        operations: dict[str, str] | None = None,
+    ) -> None:
+        self._driver = driver
+        self._operations = {
+            "load": LOAD,
+            "try_reserve": TRY_RESERVE,
+            "settle": SETTLE,
+            "release": RELEASE,
+            "snapshot": SNAPSHOT,
+            **(operations or {}),
+        }
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        result = await self._driver.call(self._operations["load"], {"stackId": stack_id})
+        assert isinstance(result, dict)
+        return _row_to_stack(result), _row_to_usage_map(result["usages"])
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        result = await self._driver.call(
+            self._operations["try_reserve"],
+            {"stackId": stack_id, "req": _spend_request_to_row(req)},
+        )
+        assert isinstance(result, dict)
+        return _row_to_decision(result)
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        await self._driver.call(
+            self._operations["settle"],
+            {
+                "stackId": stack_id,
+                "reservation": _reservation_to_row(reservation),
+                "actual": actual,
+            },
+        )
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        await self._driver.call(
+            self._operations["release"],
+            {"stackId": stack_id, "reservation": _reservation_to_row(reservation)},
+        )
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        result = await self._driver.call(self._operations["snapshot"], {"stackId": stack_id})
+        return _row_to_usage_map(result)
+
+
+def create_budget_operations(initial: InitialState) -> list[ConvexStoreOperation]:
+    state: dict[str, _StackState] = {
+        stack_id: {
+            "stack": [_budget_to_row(budget) for budget in stack],
+            "usages": _usage_map_to_row(usages),
+            "openReservations": [],
+        }
+        for stack_id, (stack, usages) in initial.items()
+    }
+
+    async def load(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        return {
+            "stack": deepcopy(current["stack"]),
+            "usages": deepcopy(current["usages"]),
+        }
+
+    async def try_reserve(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        decision = check_stack(stack, usages, _row_to_spend_request(input_value["req"]))
+        if not decision.ok or decision.reservation is None:
+            return _decision_to_row(decision)
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(
+                reserve_stack(stack, usages, _row_to_spend_request(input_value["req"]))
+            ),
+            "openReservations": [*current["openReservations"], decision.reservation.id],
+        }
+        return _decision_to_row(decision)
+
+    async def settle(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        reservation = _row_to_reservation(input_value["reservation"])
+        if reservation.id not in current["openReservations"]:
+            return None
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(
+                settle_stack(stack, usages, reservation, input_value["actual"])
+            ),
+            "openReservations": [
+                item for item in current["openReservations"] if item != reservation.id
+            ],
+        }
+        return None
+
+    async def release(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        assert isinstance(input_value, dict)
+        stack_id = _stack_id_from(input_value)
+        current = _require_stack(state, stack_id)
+        reservation = _row_to_reservation(input_value["reservation"])
+        if reservation.id not in current["openReservations"]:
+            return None
+        stack = _row_to_stack(current)
+        usages = _row_to_usage_map(current["usages"])
+        state[stack_id] = {
+            **current,
+            "usages": _usage_map_to_row(release_stack(stack, usages, reservation)),
+            "openReservations": [
+                item for item in current["openReservations"] if item != reservation.id
+            ],
+        }
+        return None
+
+    async def snapshot(_ctx: ConvexOperationContext, input_value: JsonValue) -> JsonValue:
+        stack_id = _stack_id_from(input_value)
+        return deepcopy(_require_stack(state, stack_id)["usages"])
+
+    return [
+        ConvexStoreOperation(name=LOAD, kind="query", run=load),
+        ConvexStoreOperation(name=TRY_RESERVE, kind="mutation", run=try_reserve),
+        ConvexStoreOperation(name=SETTLE, kind="mutation", run=settle),
+        ConvexStoreOperation(name=RELEASE, kind="mutation", run=release),
+        ConvexStoreOperation(name=SNAPSHOT, kind="query", run=snapshot),
+    ]
+
+
+def _require_stack(state: dict[str, _StackState], stack_id: str) -> _StackState:
+    try:
+        return state[stack_id]
+    except KeyError as exc:
+        raise KeyError(f"Unknown budget stack: {stack_id}") from exc
+
+
+def _stack_id_from(input_value: JsonValue) -> str:
+    assert isinstance(input_value, dict)
+    stack_id = input_value.get("stackId")
+    if not isinstance(stack_id, str):
+        raise ValueError("Convex budget operation requires stackId")
+    return stack_id
+
+
+def _budget_to_row(budget: Budget) -> dict[str, Any]:
+    return {"id": budget.id, "layer": budget.layer, "limits": dict(budget.limits)}
+
+
+def _row_to_budget(row: Any) -> Budget:
+    return Budget(id=row["id"], layer=row["layer"], limits=dict(row["limits"]))
+
+
+def _usage_to_row(usage: Usage) -> dict[str, Any]:
+    return {
+        "cumulative": dict(usage.cumulative),
+        "concurrent": dict(usage.concurrent),
+        "peak": dict(usage.peak),
+        "reserved": dict(usage.reserved),
+    }
+
+
+def _row_to_usage(row: Any) -> Usage:
+    return Usage(
+        cumulative=dict(row["cumulative"]),
+        concurrent=dict(row["concurrent"]),
+        peak=dict(row["peak"]),
+        reserved=dict(row["reserved"]),
+    )
+
+
+def _usage_map_to_row(usages: UsageMap) -> dict[str, Any]:
+    return {budget_id: _usage_to_row(usage) for budget_id, usage in usages.items()}
+
+
+def _row_to_usage_map(row: Any) -> UsageMap:
+    return {budget_id: _row_to_usage(usage) for budget_id, usage in deepcopy(row).items()}
+
+
+def _row_to_stack(row: Any) -> list[Budget]:
+    return [_row_to_budget(budget) for budget in deepcopy(row["stack"])]
+
+
+def _spend_request_to_row(req: SpendRequest) -> dict[str, Any]:
+    return {"estimate": dict(req.estimate), "run_id": req.run_id}
+
+
+def _row_to_spend_request(row: Any) -> SpendRequest:
+    return SpendRequest(estimate=dict(row["estimate"]), run_id=row.get("run_id"))
+
+
+def _reservation_to_row(reservation: Reservation) -> dict[str, Any]:
+    return {"id": reservation.id, "estimate": dict(reservation.estimate)}
+
+
+def _row_to_reservation(row: Any) -> Reservation:
+    return Reservation(id=row["id"], estimate=dict(row["estimate"]))
+
+
+def _decision_to_row(decision: Decision) -> dict[str, Any]:
+    if decision.ok:
+        assert decision.reservation is not None
+        return {"ok": True, "reservation": _reservation_to_row(decision.reservation)}
+    assert decision.breach is not None
+    return {
+        "ok": False,
+        "breach": {
+            "budget_id": decision.breach.budget_id,
+            "layer": decision.breach.layer,
+            "dimension": decision.breach.dimension,
+            "limit": decision.breach.limit,
+            "would_be": decision.breach.would_be,
+        },
+    }
+
+
+def _row_to_decision(row: Any) -> Decision:
+    if row["ok"]:
+        return Decision(ok=True, reservation=_row_to_reservation(row["reservation"]))
+    breach = row["breach"]
+    from .core import Breach
+
+    return Decision(
+        ok=False,
+        breach=Breach(
+            budget_id=breach["budget_id"],
+            layer=breach["layer"],
+            dimension=breach["dimension"],
+            limit=breach["limit"],
+            would_be=breach["would_be"],
+        ),
+    )

deltav/store_local.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+import asyncio
+from copy import deepcopy
+
+from .core import (
+    Budget,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    UsageMap,
+    check_stack,
+    release_stack,
+    reserve_stack,
+    settle_stack,
+)
+
+
+class InMemoryBudgetStore:
+    def __init__(self, initial: dict[str, tuple[list[Budget], UsageMap]] | None = None) -> None:
+        self._stacks: dict[str, tuple[list[Budget], UsageMap]] = initial or {}
+        self._open: dict[str, set[str]] = {stack_id: set() for stack_id in self._stacks}
+        self._lock = asyncio.Lock()
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        async with self._lock:
+            stack, usages = self._require(stack_id)
+            return list(stack), deepcopy(usages)
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        async with self._lock:
+            stack, usages = self._require(stack_id)
+            decision = check_stack(stack, usages, req)
+            if decision.ok and decision.reservation is not None:
+                self._stacks[stack_id] = (stack, reserve_stack(stack, usages, req))
+                self._open.setdefault(stack_id, set()).add(decision.reservation.id)
+            return decision
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        async with self._lock:
+            if reservation.id not in self._open.setdefault(stack_id, set()):
+                return
+            stack, usages = self._require(stack_id)
+            self._stacks[stack_id] = (stack, settle_stack(stack, usages, reservation, actual))
+            self._open[stack_id].remove(reservation.id)
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        async with self._lock:
+            if reservation.id not in self._open.setdefault(stack_id, set()):
+                return
+            stack, usages = self._require(stack_id)
+            self._stacks[stack_id] = (stack, release_stack(stack, usages, reservation))
+            self._open[stack_id].remove(reservation.id)
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        async with self._lock:
+            return deepcopy(self._require(stack_id)[1])
+
+    def _require(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        if stack_id not in self._stacks:
+            raise KeyError(f"Unknown budget stack: {stack_id}")
+        return self._stacks[stack_id]

deltav/store_postgres.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+from typing import Any
+
+from dockbay import (
+    PostgresStoreDriver,
+    PostgresStoreDriverOptions,
+    Row,
+    StoreDriver,
+    Transaction,
+    create_postgres_driver,
+)
+from psycopg_pool import AsyncConnectionPool
+
+from .core import (
+    Budget,
+    Decision,
+    Reservation,
+    Spend,
+    SpendRequest,
+    Usage,
+    UsageMap,
+    check_stack,
+    release_stack,
+    reserve_stack,
+    settle_stack,
+)
+
+TABLE = "budget_stacks"
+MAX_CAS_ATTEMPTS = 25
+
+InitialState = dict[str, tuple[list[Budget], UsageMap]]
+_Update = Callable[[Row], tuple[Any, Row]]
+
+
+class DriverBudgetStore:
+    def __init__(self, driver: StoreDriver, initial: InitialState | None = None) -> None:
+        self._driver = driver
+        self._initial = initial or {}
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        async def work(txn: Transaction) -> tuple[list[Budget], UsageMap]:
+            state = await self._load_state(txn, stack_id)
+            return _row_to_stack(state), _row_to_usage_map(state["usages"])
+
+        return await self._driver.transaction(work)
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        def update(state: Row) -> tuple[Decision, Row]:
+            stack = _row_to_stack(state)
+            usages = _row_to_usage_map(state["usages"])
+            decision = check_stack(stack, usages, req)
+            if not decision.ok or decision.reservation is None:
+                return decision, state
+            next_state = {
+                **state,
+                "usages": _usage_map_to_row(reserve_stack(stack, usages, req)),
+                "openReservations": [*state["openReservations"], decision.reservation.id],
+            }
+            return decision, next_state
+
+        return await self._cas(stack_id, update)
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        def update(state: Row) -> tuple[None, Row]:
+            if reservation.id not in state["openReservations"]:
+                return None, state
+            stack = _row_to_stack(state)
+            usages = _row_to_usage_map(state["usages"])
+            next_state = {
+                **state,
+                "usages": _usage_map_to_row(settle_stack(stack, usages, reservation, actual)),
+                "openReservations": [
+                    item for item in state["openReservations"] if item != reservation.id
+                ],
+            }
+            return None, next_state
+
+        await self._cas(stack_id, update)
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        def update(state: Row) -> tuple[None, Row]:
+            if reservation.id not in state["openReservations"]:
+                return None, state
+            stack = _row_to_stack(state)
+            usages = _row_to_usage_map(state["usages"])
+            next_state = {
+                **state,
+                "usages": _usage_map_to_row(release_stack(stack, usages, reservation)),
+                "openReservations": [
+                    item for item in state["openReservations"] if item != reservation.id
+                ],
+            }
+            return None, next_state
+
+        await self._cas(stack_id, update)
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        async def work(txn: Transaction) -> UsageMap:
+            state = await self._load_state(txn, stack_id)
+            return _row_to_usage_map(state["usages"])
+
+        return await self._driver.transaction(work)
+
+    async def close(self) -> None:
+        await self._driver.close()
+
+    async def _cas(self, stack_id: str, update: _Update) -> Any:
+        for _ in range(MAX_CAS_ATTEMPTS):
+            outcome = await self._driver.transaction(
+                _attempt_update(stack_id, self._load_state, update)
+            )
+            if outcome["applied"]:
+                return outcome["result"]
+        raise RuntimeError(f"Budget stack update conflicted too often: {stack_id}")
+
+    async def _load_state(self, txn: Transaction, stack_id: str) -> Row:
+        existing = await txn.get(TABLE, _stack_key(stack_id))
+        if existing is not None:
+            return existing
+        seed = self._initial.get(stack_id)
+        if seed is None:
+            raise KeyError(f"Unknown budget stack: {stack_id}")
+        stack, usages = seed
+        state = {
+            "stack": [_budget_to_row(budget) for budget in stack],
+            "usages": _usage_map_to_row(usages),
+            "openReservations": [],
+        }
+        await txn.compare_and_apply(TABLE, _stack_key(stack_id), None, state)
+        return state
+
+
+class PostgresBudgetStore(DriverBudgetStore):
+    def __init__(
+        self,
+        pool: AsyncConnectionPool,
+        *,
+        table: str = "deltav_budget_store",
+        initial: InitialState | None = None,
+    ) -> None:
+        self.postgres_driver: PostgresStoreDriver = create_postgres_driver(
+            pool, PostgresStoreDriverOptions(table=table)
+        )
+        super().__init__(self.postgres_driver, initial)
+
+
+def _attempt_update(
+    stack_id: str,
+    load_state: Callable[[Transaction, str], Awaitable[Row]],
+    update: _Update,
+) -> Callable[[Transaction], Awaitable[Row]]:
+    async def work(txn: Transaction) -> Row:
+        state = await load_state(txn, stack_id)
+        result, next_state = update(state)
+        if state == next_state:
+            return {"applied": True, "result": result}
+        applied = await txn.compare_and_apply(TABLE, _stack_key(stack_id), state, next_state)
+        return {"applied": applied, "result": result}
+
+    return work
+
+
+def _stack_key(stack_id: str) -> Row:
+    return {"stackId": stack_id}
+
+
+def _budget_to_row(budget: Budget) -> Row:
+    return {"id": budget.id, "layer": budget.layer, "limits": dict(budget.limits)}
+
+
+def _row_to_budget(row: Row) -> Budget:
+    return Budget(id=row["id"], layer=row["layer"], limits=dict(row["limits"]))
+
+
+def _usage_to_row(usage: Usage) -> Row:
+    return {
+        "cumulative": dict(usage.cumulative),
+        "concurrent": dict(usage.concurrent),
+        "peak": dict(usage.peak),
+        "reserved": dict(usage.reserved),
+    }
+
+
+def _row_to_usage(row: Row) -> Usage:
+    return Usage(
+        cumulative=dict(row["cumulative"]),
+        concurrent=dict(row["concurrent"]),
+        peak=dict(row["peak"]),
+        reserved=dict(row["reserved"]),
+    )
+
+
+def _usage_map_to_row(usages: UsageMap) -> Row:
+    return {budget_id: _usage_to_row(usage) for budget_id, usage in usages.items()}
+
+
+def _row_to_usage_map(row: Any) -> UsageMap:
+    return {budget_id: _row_to_usage(usage) for budget_id, usage in deepcopy(row).items()}
+
+
+def _row_to_stack(row: Row) -> list[Budget]:
+    return [_row_to_budget(budget) for budget in deepcopy(row["stack"])]

deltav/store_remote.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import cast
+
+from .core import Breach, Budget, Decision, Reservation, Spend, SpendRequest, Usage, UsageMap
+
+HttpRequest = Callable[[str, str, object | None], Awaitable[object]]
+
+
+@dataclass(frozen=True)
+class RemoteBudgetStore:
+    request: HttpRequest
+    default_stack_id: str
+
+    async def load(self, stack_id: str) -> tuple[list[Budget], UsageMap]:
+        body = await self.request("POST", "/budget/load", {"stackId": stack_id})
+        if not isinstance(body, dict):
+            raise TypeError("Remote budget load returned a non-object response")
+        body_map = cast(dict[str, object], body)
+        stack_value = body_map.get("stack", [])
+        usages_value = body_map.get("usages", {})
+        return (
+            [_budget(value) for value in _list(stack_value)],
+            _usage_map(usages_value),
+        )
+
+    async def try_reserve(self, stack_id: str, req: SpendRequest) -> Decision:
+        body = await self.request(
+            "POST", "/budget/try-reserve", {"stackId": stack_id, "request": req}
+        )
+        return _decision(body)
+
+    async def settle(self, stack_id: str, reservation: Reservation, actual: Spend) -> None:
+        await self.request(
+            "POST",
+            "/budget/settle",
+            {"stackId": stack_id, "reservation": reservation, "actual": actual},
+        )
+
+    async def release(self, stack_id: str, reservation: Reservation) -> None:
+        await self.request(
+            "POST", "/budget/release", {"stackId": stack_id, "reservation": reservation}
+        )
+
+    async def snapshot(self, stack_id: str) -> UsageMap:
+        body = await self.request("POST", "/budget/snapshot", {"stackId": stack_id})
+        return _usage_map(body)
+
+
+def _budget(value: object) -> Budget:
+    if isinstance(value, Budget):
+        return value
+    if not isinstance(value, dict):
+        raise TypeError("Budget value must be an object")
+    value_map = cast(dict[str, object], value)
+    limits = value_map["limits"]
+    if not isinstance(limits, dict):
+        raise TypeError("Budget limits must be an object")
+    return Budget(
+        id=str(value_map["id"]),
+        layer=str(value_map["layer"]),
+        limits={str(key): _number(amount) for key, amount in limits.items()},
+    )
+
+
+def _usage(value: object) -> Usage:
+    if isinstance(value, Usage):
+        return value
+    if not isinstance(value, dict):
+        raise TypeError("Usage value must be an object")
+    value_map = cast(dict[str, object], value)
+    return Usage(
+        cumulative=_spend(value_map.get("cumulative", {})),
+        concurrent=_spend(value_map.get("concurrent", {})),
+        peak=_spend(value_map.get("peak", {})),
+        reserved=_spend(value_map.get("reserved", {})),
+    )
+
+
+def _usage_map(value: object) -> UsageMap:
+    if not isinstance(value, dict):
+        raise TypeError("Usage map must be an object")
+    value_map = cast(dict[str, object], value)
+    return {str(key): _usage(item) for key, item in value_map.items()}
+
+
+def _decision(value: object) -> Decision:
+    if isinstance(value, Decision):
+        return value
+    if not isinstance(value, dict):
+        raise TypeError("Decision value must be an object")
+    value_map = cast(dict[str, object], value)
+    if value_map.get("ok") is True:
+        return Decision(ok=True, reservation=_reservation(value_map.get("reservation")))
+    return Decision(ok=False, breach=_breach(value_map.get("breach")))
+
+
+def _reservation(value: object) -> Reservation:
+    if isinstance(value, Reservation):
+        return value
+    if not isinstance(value, dict):
+        raise TypeError("Reservation value must be an object")
+    value_map = cast(dict[str, object], value)
+    return Reservation(id=str(value_map["id"]), estimate=_spend(value_map["estimate"]))
+
+
+def _breach(value: object) -> Breach:
+    if isinstance(value, Breach):
+        return value
+    if not isinstance(value, dict):
+        raise TypeError("Breach value must be an object")
+    value_map = cast(dict[str, object], value)
+    return Breach(
+        budget_id=str(value_map["budget_id"]),
+        layer=str(value_map["layer"]),
+        dimension=str(value_map["dimension"]),
+        limit=_number(value_map["limit"]),
+        would_be=_number(value_map["would_be"]),
+    )
+
+
+def _spend(value: object) -> Spend:
+    if not isinstance(value, dict):
+        raise TypeError("Spend value must be an object")
+    value_map = cast(dict[str, object], value)
+    return {str(key): _number(amount) for key, amount in value_map.items()}
+
+
+def _list(value: object) -> list[object]:
+    if not isinstance(value, list):
+        raise TypeError("Value must be a list")
+    return cast(list[object], value)
+
+
+def _number(value: object) -> float:
+    if not isinstance(value, int | float):
+        raise TypeError("Value must be numeric")
+    return float(value)

deltav-0.0.0.dist-info/METADATA

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: deltav
+Version: 0.0.0
+Summary: DeltaV reservation-based budget enforcement for agent and tool runs.
+Project-URL: Homepage, https://github.com/cachetronaut/deltav
+Project-URL: Repository, https://github.com/cachetronaut/deltav
+Project-URL: Issues, https://github.com/cachetronaut/deltav/issues
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: dockbay>=0.0.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg[binary]>=3.2
+Description-Content-Type: text/markdown
+
+# deltav
+
+Python implementation of DeltaV.
+
+For product-level context, shared contracts, and cross-language repository information, see the public repository: https://github.com/cachetronaut/deltav.
+
+## Install
+
+```sh
+pip install deltav
+```
+
+## Import
+
+```python
+import deltav
+```
+
+## Development
+
+Run from `py/`:
+
+```sh
+uv sync --dev
+uv run --with ruff ruff check .
+uv run --with ruff ruff format --check .
+uv run --with ty ty check
+uv run --with pytest --with pytest-asyncio python -m pytest
+```
+
+## License
+
+MIT

deltav-0.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+deltav/__init__.py,sha256=zDOKPV-mfK4thYAH3VAtDfzru6vHjyMgttris0WVZTY,1028
+deltav/core.py,sha256=Akj_t7hGV3Jgg4hHLxXJtK2Q_W-9DjLjc5qQpu_nXBM,5286
+deltav/store_convex.py,sha256=ep4yA2kfa0jWT7evBqeg_Ju5nQ0XUmUj1s5eYvJao2s,9395
+deltav/store_local.py,sha256=zqMbW2X0D1mTTzC9-uDDy6QZTUioAXwr3uRa-S3sLtU,2469
+deltav/store_postgres.py,sha256=pBwhqK1SW6pWXJhIj8xCFWy8u8dE_i9UfmL03xfB-3c,6890
+deltav/store_remote.py,sha256=9Vma1BHq7gAhPyB7sUe0R4lQKCmuRsD6oq7azVqa69Q,4957
+deltav-0.0.0.dist-info/METADATA,sha256=24dQI1FGszDbRu_Tl2cOGbuSpwKbaTtajEvXIY1pLBo,1013
+deltav-0.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+deltav-0.0.0.dist-info/RECORD,,

deltav-0.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any