q-runtime-core 0.9.0__py3-none-any.whl

qruntime/core/model.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from enum import Enum
+from typing import Iterable
+
+
+class StepStatus(str, Enum):
+    PENDING = "PENDING"
+    RESERVED = "RESERVED"
+    PAID = "PAID"
+    DONE = "DONE"
+
+
+class TaskStatus(str, Enum):
+    AUTHORIZED = "AUTHORIZED"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+
+
+@dataclass(frozen=True)
+class StepSpec:
+    id: str
+    max_cost: int  # integer minor units
+    actual_cost: int
+    required: bool = True
+    dependencies: tuple[str, ...] = ()
+    required_evidence: tuple[str, ...] = ()
+    actor: str = "agent"
+    allowed_actors: tuple[str, ...] = ("agent",)
+    allow_ambiguous_retry: bool = False
+    allow_missing_evidence_spend: bool = False
+    allow_unauthorized_execution: bool = False
+
+
+@dataclass(frozen=True)
+class WorkflowSpec:
+    name: str
+    currency: str
+    budget: int
+    steps: tuple[StepSpec, ...]
+    max_states: int = 10_000
+
+    def step(self, step_id: str) -> StepSpec:
+        for step in self.steps:
+            if step.id == step_id:
+                return step
+        raise KeyError(step_id)
+
+
+@dataclass(frozen=True)
+class RuntimeState:
+    task_status: TaskStatus
+    spent: int
+    reserved: int
+    step_statuses: tuple[tuple[str, StepStatus], ...]
+    attempts: tuple[tuple[str, int], ...]
+    settled_intents: tuple[str, ...] = ()
+    evidence: tuple[str, ...] = ()
+    ambiguous_intents: tuple[str, ...] = ()
+    unauthorized_effects: tuple[str, ...] = ()
+    evidence_bypasses: tuple[str, ...] = ()
+
+    @staticmethod
+    def initial(spec: WorkflowSpec) -> "RuntimeState":
+        return RuntimeState(
+            task_status=TaskStatus.AUTHORIZED,
+            spent=0,
+            reserved=0,
+            step_statuses=tuple((s.id, StepStatus.PENDING) for s in spec.steps),
+            attempts=tuple((s.id, 0) for s in spec.steps),
+        )
+
+    def status(self, step_id: str) -> StepStatus:
+        return dict(self.step_statuses)[step_id]
+
+    def attempt(self, step_id: str) -> int:
+        return dict(self.attempts)[step_id]
+
+    def with_step_status(self, step_id: str, status: StepStatus) -> "RuntimeState":
+        data = dict(self.step_statuses)
+        data[step_id] = status
+        return replace(self, step_statuses=tuple(sorted(data.items())))
+
+    def with_attempt(self, step_id: str, attempt: int) -> "RuntimeState":
+        data = dict(self.attempts)
+        data[step_id] = attempt
+        return replace(self, attempts=tuple(sorted(data.items())))
+
+    def with_evidence(self, evidence_id: str) -> "RuntimeState":
+        return replace(self, evidence=tuple(sorted(set(self.evidence) | {evidence_id})))
+
+    def with_settled_intent(self, intent_id: str) -> "RuntimeState":
+        # Deliberately retain duplicates: the invariant is responsible for rejecting them.
+        return replace(self, settled_intents=tuple(sorted(self.settled_intents + (intent_id,))))
+
+    def with_ambiguous_intent(self, intent_id: str) -> "RuntimeState":
+        return replace(self, ambiguous_intents=tuple(sorted(set(self.ambiguous_intents) | {intent_id})))
+
+    def with_unauthorized_effect(self, detail: str) -> "RuntimeState":
+        return replace(self, unauthorized_effects=tuple(sorted(self.unauthorized_effects + (detail,))))
+
+    def with_evidence_bypass(self, step_id: str) -> "RuntimeState":
+        return replace(self, evidence_bypasses=tuple(sorted(self.evidence_bypasses + (step_id,))))
+
+
+@dataclass(frozen=True)
+class Action:
+    kind: str
+    step_id: str | None = None
+    detail: str = ""
+
+    def label(self) -> str:
+        if self.step_id:
+            return f"{self.kind}({self.step_id}){': ' + self.detail if self.detail else ''}"
+        return f"{self.kind}{': ' + self.detail if self.detail else ''}"
+
+
+def all_required_done(spec: WorkflowSpec, state: RuntimeState) -> bool:
+    return all((not step.required) or state.status(step.id) == StepStatus.DONE for step in spec.steps)
+
+
+def dependencies_done(step: StepSpec, state: RuntimeState) -> bool:
+    return all(state.status(dep) == StepStatus.DONE for dep in step.dependencies)
+
+
+def evidence_present(step: StepSpec, state: RuntimeState) -> bool:
+    available = set(state.evidence)
+    return all(e in available for e in step.required_evidence)
+
+
+def unresolved_required_cost(spec: WorkflowSpec, state: RuntimeState, exclude: Iterable[str] = ()) -> int:
+    excluded = set(exclude)
+    total = 0
+    for step in spec.steps:
+        if not step.required or step.id in excluded:
+            continue
+        if state.status(step.id) == StepStatus.PENDING:
+            total += step.max_cost
+    return total

qruntime/core/transition.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .model import (
+    Action,
+    RuntimeState,
+    StepStatus,
+    TaskStatus,
+    WorkflowSpec,
+    all_required_done,
+    dependencies_done,
+    evidence_present,
+)
+
+
+def enabled_actions(spec: WorkflowSpec, state: RuntimeState) -> list[Action]:
+    if state.task_status == TaskStatus.COMPLETED:
+        return []
+
+    actions: list[Action] = []
+    for step in spec.steps:
+        status = state.status(step.id)
+        if status == StepStatus.PENDING and dependencies_done(step, state):
+            has_evidence = evidence_present(step, state)
+            actor_allowed = step.actor in step.allowed_actors
+            if has_evidence and actor_allowed:
+                actions.append(Action("reserve", step.id))
+            elif not has_evidence and step.allow_missing_evidence_spend:
+                actions.append(Action("reserve_without_evidence", step.id))
+            elif not actor_allowed and step.allow_unauthorized_execution:
+                actions.append(Action("reserve_unauthorized", step.id, f"actor={step.actor}"))
+        elif status == StepStatus.RESERVED:
+            actions.append(Action("settle", step.id))
+        elif status == StepStatus.PAID:
+            actions.append(Action("deliver", step.id))
+            if step.allow_ambiguous_retry:
+                actions.append(Action("retry_ambiguous", step.id, "payment outcome treated as retryable before reconciliation"))
+
+    if all_required_done(spec, state):
+        actions.append(Action("complete"))
+    return actions
+
+
+def _reserve(spec: WorkflowSpec, state: RuntimeState, step_id: str) -> RuntimeState:
+    step = spec.step(step_id)
+    next_state = state.with_step_status(step.id, StepStatus.RESERVED)
+    return replace(
+        next_state,
+        task_status=TaskStatus.RUNNING,
+        reserved=state.reserved + step.max_cost,
+    )
+
+
+def apply_action(spec: WorkflowSpec, state: RuntimeState, action: Action) -> RuntimeState:
+    if action.kind == "complete":
+        return replace(state, task_status=TaskStatus.COMPLETED)
+
+    assert action.step_id is not None
+    step = spec.step(action.step_id)
+
+    if action.kind == "reserve":
+        return _reserve(spec, state, step.id)
+
+    if action.kind == "reserve_without_evidence":
+        return _reserve(spec, state, step.id).with_evidence_bypass(step.id)
+
+    if action.kind == "reserve_unauthorized":
+        detail = f"{step.id}:{step.actor}"
+        return _reserve(spec, state, step.id).with_unauthorized_effect(detail)
+
+    if action.kind == "settle":
+        next_state = state.with_step_status(step.id, StepStatus.PAID)
+        next_state = next_state.with_attempt(step.id, state.attempt(step.id) + 1)
+        next_state = next_state.with_settled_intent(step.id)
+        return replace(
+            next_state,
+            reserved=state.reserved - step.max_cost,
+            spent=state.spent + step.actual_cost,
+        )
+
+    if action.kind == "deliver":
+        next_state = state.with_step_status(step.id, StepStatus.DONE)
+        return next_state.with_evidence(f"delivered:{step.id}")
+
+    if action.kind == "retry_ambiguous":
+        # Models the dangerous recovery path: execution is reopened while the prior
+        # payment outcome is still unresolved. The invariant should reject this immediately.
+        next_state = state.with_step_status(step.id, StepStatus.PENDING)
+        return next_state.with_ambiguous_intent(step.id)
+
+    raise ValueError(f"unknown action: {action.kind}")

qruntime/exceptions.py

@@ -0,0 +1,132 @@
+class QRuntimeError(RuntimeError):
+    """Base exception for public Q Runtime operational errors."""
+
+
+class PaymentSafetyError(QRuntimeError):
+    """Base exception for payment safety refusals."""
+
+
+class IntentInFlightError(PaymentSafetyError):
+    """The same logical payment intent is already running elsewhere."""
+
+
+class IntentResourceMismatchError(PaymentSafetyError):
+    """An existing intent is already bound to another resource."""
+
+
+class SettlementPendingError(PaymentSafetyError):
+    """A settlement is unresolved and must be reconciled before retry."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        transaction: str | None = None,
+        network: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.transaction = transaction
+        self.network = network
+
+
+class DuplicateIntentError(PaymentSafetyError):
+    """The logical intent already produced a confirmed economic effect."""
+
+
+class PaymentRequirementRejectedError(PaymentSafetyError):
+    """No offered payment requirement satisfies the runtime policy."""
+
+
+class PaymentRequirementMismatchError(PaymentSafetyError):
+    """The payment requirement is not bound to the controlled resource."""
+
+
+class SettlementReceiptError(QRuntimeError):
+    """The settlement receipt is missing or inconsistent."""
+
+
+class SettlementFailedError(QRuntimeError):
+    """Settlement reached a terminal failure."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        reason: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.reason = reason
+
+
+class PaidResourceError(QRuntimeError):
+    """Payment settled, but the paid resource request failed."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        transaction: str | None = None,
+        network: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.transaction = transaction
+        self.network = network
+
+
+class SettlementStoreError(QRuntimeError):
+    """Persistent settlement state could not be safely read or updated."""
+
+
+class ReconciliationError(QRuntimeError):
+    """Settlement reconciliation infrastructure failed."""
+
+
+class PolicyDeniedError(PaymentSafetyError):
+    """Policy evaluation denied an economic operation."""
+
+    def __init__(self, decision: "PolicyDecision") -> None:
+        self.decision = decision
+        self.reason_codes = tuple(
+            decision.reason_codes
+        )
+
+        message = (
+            "policy denied economic operation"
+        )
+
+        if self.reason_codes:
+            message += ": " + ", ".join(
+                self.reason_codes
+            )
+
+        super().__init__(message)
+
+class BudgetDeniedError(PaymentSafetyError):
+    """Aggregate spending budget refused the payment."""
+
+    def __init__(self, decision):
+        self.decision = decision
+        self.reason = getattr(
+            decision,
+            "reason",
+            None,
+        )
+        self.projected_atomic = getattr(
+            decision,
+            "projected_atomic",
+            None,
+        )
+        self.limit_atomic = getattr(
+            decision,
+            "limit_atomic",
+            None,
+        )
+
+        super().__init__(
+            "budget denied payment: "
+            f"{self.reason or 'aggregate_budget_exceeded'}; "
+            f"projected={self.projected_atomic}; "
+            f"limit={self.limit_atomic}"
+        )

qruntime/integrations/official_x402_demo.py

@@ -0,0 +1,94 @@
+"""Optional official x402 SDK demo server for Q Runtime v0.6.
+
+This module uses the x402 Foundation Python SDK and mirrors the current official
+FastAPI example's EVM/Base-Sepolia path. It is testnet-only by design.
+"""
+from __future__ import annotations
+
+
+def build_app(
+    *,
+    pay_to: str,
+    price_usd: str = "0.01",
+    facilitator_url: str = "https://x402.org/facilitator",
+):
+    try:
+        from fastapi import FastAPI
+        from x402.http import FacilitatorConfig, HTTPFacilitatorClient, PaymentOption
+        from x402.http.middleware.fastapi import PaymentMiddlewareASGI
+        from x402.http.types import RouteConfig
+        from x402.mechanisms.evm.exact import ExactEvmServerScheme
+        from x402.server import x402ResourceServer
+    except ImportError as exc:  # pragma: no cover - exercised in user's optional integration env
+        raise RuntimeError(
+            "official x402 integration dependencies are missing. Install with: "
+            'python -m pip install -e ".[official-x402]"'
+        ) from exc
+
+    if not pay_to.startswith("0x") or len(pay_to) != 42:
+        raise ValueError("--pay-to must be a 20-byte EVM address (0x + 40 hex characters)")
+    try:
+        int(pay_to[2:], 16)
+    except ValueError as exc:
+        raise ValueError("--pay-to is not valid hexadecimal") from exc
+
+    try:
+        amount = float(price_usd)
+    except ValueError as exc:
+        raise ValueError("--price-usd must be numeric, e.g. 0.01") from exc
+    if amount <= 0:
+        raise ValueError("--price-usd must be positive")
+
+    # Current official example uses Base Sepolia for its EVM testnet server path.
+    network = "eip155:84532"
+
+    app = FastAPI(title="Q Runtime v0.6 — Official x402 SDK Capture Demo")
+    facilitator = HTTPFacilitatorClient(FacilitatorConfig(url=facilitator_url))
+    server = x402ResourceServer(facilitator)
+    server.register(network, ExactEvmServerScheme())
+
+    routes = {
+        "GET /weather": RouteConfig(
+            accepts=[
+                PaymentOption(
+                    scheme="exact",
+                    pay_to=pay_to,
+                    price=f"${amount:.2f}",
+                    network=network,
+                )
+            ],
+            mime_type="application/json",
+            description="Weather report — Q Runtime x402 capture demo",
+        )
+    }
+    app.add_middleware(PaymentMiddlewareASGI, routes=routes, server=server)
+
+    @app.get("/health")
+    async def health() -> dict[str, str]:
+        return {"status": "ok", "network": network}
+
+    @app.get("/weather")
+    async def weather() -> dict[str, object]:
+        return {"report": {"weather": "sunny", "temperature": 70}}
+
+    return app
+
+
+def serve(
+    *,
+    pay_to: str,
+    price_usd: str = "0.01",
+    host: str = "127.0.0.1",
+    port: int = 4021,
+    facilitator_url: str = "https://x402.org/facilitator",
+) -> None:
+    try:
+        import uvicorn
+    except ImportError as exc:  # pragma: no cover
+        raise RuntimeError(
+            "uvicorn is missing. Install with: "
+            'python -m pip install -e ".[official-x402]"'
+        ) from exc
+
+    app = build_app(pay_to=pay_to, price_usd=price_usd, facilitator_url=facilitator_url)
+    uvicorn.run(app, host=host, port=port)

qruntime/loader.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from pathlib import Path
+import yaml
+
+from qruntime.core.model import StepSpec, WorkflowSpec
+
+
+def money_to_minor(value: float | int | str) -> int:
+    return int(round(float(value) * 100))
+
+
+def load_workflow(path: str | Path) -> WorkflowSpec:
+    raw = yaml.safe_load(Path(path).read_text(encoding="utf-8"))
+    steps = []
+    for item in raw.get("steps", []):
+        max_cost = money_to_minor(item["max_cost"])
+        actor = str(item.get("actor", "agent"))
+        allowed_actors = tuple(str(x) for x in item.get("allowed_actors", [actor]))
+        steps.append(StepSpec(
+            id=item["id"],
+            max_cost=max_cost,
+            actual_cost=money_to_minor(item.get("actual_cost", item["max_cost"])),
+            required=bool(item.get("required", True)),
+            dependencies=tuple(item.get("dependencies", [])),
+            required_evidence=tuple(item.get("required_evidence", [])),
+            actor=actor,
+            allowed_actors=allowed_actors,
+            allow_ambiguous_retry=bool(item.get("allow_ambiguous_retry", False)),
+            allow_missing_evidence_spend=bool(item.get("allow_missing_evidence_spend", False)),
+            allow_unauthorized_execution=bool(item.get("allow_unauthorized_execution", False)),
+        ))
+    return WorkflowSpec(
+        name=raw["workflow"],
+        currency=raw.get("currency", "USD"),
+        budget=money_to_minor(raw["budget"]),
+        steps=tuple(steps),
+        max_states=int(raw.get("max_states", 10_000)),
+    )

qruntime/policies/authority.py

@@ -0,0 +1 @@
+"""Delegated-authority policy primitives will move here in the next increment."""

qruntime/policies/budget.py

@@ -0,0 +1 @@
+"""Budget policy primitives will move here as the v0.1 model expands."""

qruntime/policies/evidence.py

@@ -0,0 +1 @@
+"""Evidence requirements will move here in the next increment."""