dispatch-kit 0.1.0__tar.gz

dispatch_kit-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: dispatch-kit
+Version: 0.1.0
+Summary: Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress.
+Author-email: Aryan Falahatpisheh <aryanfalahat@gmail.com>
+License: MIT
+Keywords: budget,cost,cloud,gpu,llm,dispatch,egress,approval
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: pylint>=3.0; extra == "dev"
+Requires-Dist: ruff>=0.1; extra == "dev"
+
+# dispatch-kit
+
+A tiny, **pure, dependency-free** library for gating expensive remote/external work — the same
+machinery for a **cloud GPU job** (a Cloud Run L4 reached over a tailnet) and a **paid LLM/SDK API
+call** (Gemini, Claude, Rowan). It answers three questions, fail-closed:
+
+- **Can we afford it?** — a hard, reserve-on-approval **budget cap** (per-run + per-month).
+- **Where should it run?** — a pure **router**: `LOCAL → LAN → CLOUD → SDK`, SDK opt-in only.
+- **Is the external call safe?** — opt-in, audited **API egress** with reference-only secrets.
+
+It owns the *policy* (afford / route / approve / egress); your app keeps its job entity,
+persistence, and executor. The transport *auth* (who may talk) is a separate concern — pair this
+with [`tailnet-guard`](https://github.com/falahat/tailnet-guard). Stdlib only; every check is
+fail-closed (default budget `0` = paid work off; SDK never auto-selected; a missing key refuses).
+
+## Use
+
+```python
+from decimal import Decimal
+from dispatch_kit import (
+    BudgetCap, BudgetState, CostRates, admits, estimate_cost,   # the hard $ cap
+    select_backend, BackendKind, ToolRequirements,              # the where
+    SecretRef, ExternalEndpoint, log_egress,                    # opt-in API egress
+    Approval,                                                   # the approval audit fact
+)
+
+# 1. Reserve-on-approval: refuse a job that would push past the cap (both windows).
+rates = CostRates(gpu_usd_per_s=Decimal("0.0008"), vcpu_usd_per_s=Decimal("0.00001"),
+                  gib_usd_per_s=Decimal("0.000002"), idle_tail_s=Decimal(600))
+cost = estimate_cost(rates, max_runtime_s=3600, vcpus=8, memory_gib=32)   # an UPPER bound
+decision = admits(cost, run_state, month_state, BudgetCap(run_usd=Decimal(50), month_usd=Decimal(500)))
+if not decision.admitted:
+    raise OverBudget(decision.reason)        # default cap is $0 — paid work is off until you set one
+
+# 2. Pick where it runs — LOCAL first, SDK only if explicitly allowed.
+backend = select_backend(my_backends, ToolRequirements(tool_id="cofold", min_vram_gb=24.0))
+
+# 3. An LLM/SDK key is a REFERENCE (env var name), resolved at call time, never logged.
+gemini = ExternalEndpoint("gemini", "https://generativelanguage.googleapis.com",
+                          SecretRef("GEMINI_API_KEY"))
+log_egress(gemini, detail="summarize")       # audit that data left the boundary
+headers = {"Authorization": gemini.bearer()} # raises if the key is unset (never an unauth call)
+```
+
+## What's in the box
+
+| Module | Purpose |
+|---|---|
+| `budget` | `BudgetCap` / `BudgetState` / `CostRates` / `admits` / `estimate_cost` — the hard, Decimal-exact, reserve-on-approval cap across a run + month window |
+| `estimate` | `CostEstimate` / `HostCapabilities` / `vram_fits` — the one "no GPU ⇒ a GPU job is infeasible" rule, shared by the gate and the router |
+| `routing` | `BackendKind` / `BackendCapabilities` / `ToolRequirements` / `select_backend` (generic over a `Routable`) — the pure `LOCAL→LAN→CLOUD→SDK` policy; SDK opt-in |
+| `egress` | `SecretRef` / `ExternalEndpoint` / `log_egress` — reference-only API keys, https-only, fail-closed on a missing key, audited egress (SDKs **and** LLM APIs) |
+| `approval` | `Approval` / `ApprovalOutcome` — the who/when/why audit fact for a gated job |
+| `dispatch` | `JobStore` / `Transport` / `WorkerExecutor` protocols + `is_lease_stale` / `should_give_up` / `Lease` — the run-it-once-recoverably contract (atomic claim, stale-reject, lease recovery); push vs pull is only the `Transport` adapter |
+
+## Notes
+
+- **The budget cap lives in your dispatch service, never the UI** — an agent hitting the API
+  directly is still gated. Default cap `$0`; if spend can't be computed, refuse.
+- **Reserve on approval, reconcile on completion** — approving reserves the estimate immediately so
+  a burst counts against the cap; the worker's true runtime reconciles `reserved → spent`.
+- **SDK / external egress is the one deliberate exception** — never the default (`allow_sdk` /
+  opt-in), always logged, the key sourced from a secret at call time and never written to a log.

dispatch_kit-0.1.0/README.md

@@ -0,0 +1,63 @@
+# dispatch-kit
+
+A tiny, **pure, dependency-free** library for gating expensive remote/external work — the same
+machinery for a **cloud GPU job** (a Cloud Run L4 reached over a tailnet) and a **paid LLM/SDK API
+call** (Gemini, Claude, Rowan). It answers three questions, fail-closed:
+
+- **Can we afford it?** — a hard, reserve-on-approval **budget cap** (per-run + per-month).
+- **Where should it run?** — a pure **router**: `LOCAL → LAN → CLOUD → SDK`, SDK opt-in only.
+- **Is the external call safe?** — opt-in, audited **API egress** with reference-only secrets.
+
+It owns the *policy* (afford / route / approve / egress); your app keeps its job entity,
+persistence, and executor. The transport *auth* (who may talk) is a separate concern — pair this
+with [`tailnet-guard`](https://github.com/falahat/tailnet-guard). Stdlib only; every check is
+fail-closed (default budget `0` = paid work off; SDK never auto-selected; a missing key refuses).
+
+## Use
+
+```python
+from decimal import Decimal
+from dispatch_kit import (
+    BudgetCap, BudgetState, CostRates, admits, estimate_cost,   # the hard $ cap
+    select_backend, BackendKind, ToolRequirements,              # the where
+    SecretRef, ExternalEndpoint, log_egress,                    # opt-in API egress
+    Approval,                                                   # the approval audit fact
+)
+
+# 1. Reserve-on-approval: refuse a job that would push past the cap (both windows).
+rates = CostRates(gpu_usd_per_s=Decimal("0.0008"), vcpu_usd_per_s=Decimal("0.00001"),
+                  gib_usd_per_s=Decimal("0.000002"), idle_tail_s=Decimal(600))
+cost = estimate_cost(rates, max_runtime_s=3600, vcpus=8, memory_gib=32)   # an UPPER bound
+decision = admits(cost, run_state, month_state, BudgetCap(run_usd=Decimal(50), month_usd=Decimal(500)))
+if not decision.admitted:
+    raise OverBudget(decision.reason)        # default cap is $0 — paid work is off until you set one
+
+# 2. Pick where it runs — LOCAL first, SDK only if explicitly allowed.
+backend = select_backend(my_backends, ToolRequirements(tool_id="cofold", min_vram_gb=24.0))
+
+# 3. An LLM/SDK key is a REFERENCE (env var name), resolved at call time, never logged.
+gemini = ExternalEndpoint("gemini", "https://generativelanguage.googleapis.com",
+                          SecretRef("GEMINI_API_KEY"))
+log_egress(gemini, detail="summarize")       # audit that data left the boundary
+headers = {"Authorization": gemini.bearer()} # raises if the key is unset (never an unauth call)
+```
+
+## What's in the box
+
+| Module | Purpose |
+|---|---|
+| `budget` | `BudgetCap` / `BudgetState` / `CostRates` / `admits` / `estimate_cost` — the hard, Decimal-exact, reserve-on-approval cap across a run + month window |
+| `estimate` | `CostEstimate` / `HostCapabilities` / `vram_fits` — the one "no GPU ⇒ a GPU job is infeasible" rule, shared by the gate and the router |
+| `routing` | `BackendKind` / `BackendCapabilities` / `ToolRequirements` / `select_backend` (generic over a `Routable`) — the pure `LOCAL→LAN→CLOUD→SDK` policy; SDK opt-in |
+| `egress` | `SecretRef` / `ExternalEndpoint` / `log_egress` — reference-only API keys, https-only, fail-closed on a missing key, audited egress (SDKs **and** LLM APIs) |
+| `approval` | `Approval` / `ApprovalOutcome` — the who/when/why audit fact for a gated job |
+| `dispatch` | `JobStore` / `Transport` / `WorkerExecutor` protocols + `is_lease_stale` / `should_give_up` / `Lease` — the run-it-once-recoverably contract (atomic claim, stale-reject, lease recovery); push vs pull is only the `Transport` adapter |
+
+## Notes
+
+- **The budget cap lives in your dispatch service, never the UI** — an agent hitting the API
+  directly is still gated. Default cap `$0`; if spend can't be computed, refuse.
+- **Reserve on approval, reconcile on completion** — approving reserves the estimate immediately so
+  a burst counts against the cap; the worker's true runtime reconciles `reserved → spent`.
+- **SDK / external egress is the one deliberate exception** — never the default (`allow_sdk` /
+  opt-in), always logged, the key sourced from a secret at call time and never written to a log.

dispatch_kit-0.1.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "dispatch-kit"
+version = "0.1.0"
+description = "Pure, fail-closed cost-gating for expensive remote/external work: a hard $ budget cap, backend routing (local->cloud->SDK), and opt-in audited API egress."
+authors = [{ name = "Aryan Falahatpisheh", email = "aryanfalahat@gmail.com" }]
+readme = "README.md"
+license = { text = "MIT" }
+keywords = ["budget", "cost", "cloud", "gpu", "llm", "dispatch", "egress", "approval"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "mypy>=1.0",
+    "black>=23.0",
+    "flake8>=6.0",
+    "pylint>=3.0",
+    "ruff>=0.1",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+dispatch_kit = ["py.typed"]
+
+# --- Quality gates (strict; zero inline suppressions — fix root causes) ---
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "C4", "SIM", "PTH", "YTT", "ARG", "RUF"]
+
+[tool.ruff.lint.per-file-ignores]
+# pytest injects fixtures by name; ARG can't see the framework consumes them.
+"tests/**" = ["ARG001", "ARG002"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+addopts = ["-q"]
+
+[tool.coverage.run]
+source = ["src/dispatch_kit"]
+omit = ["*/tests/*"]
+
+[tool.pylint.main]
+source-roots = ["src"]
+
+[tool.pylint.format]
+max-line-length = 100
+
+[tool.pylint.design]
+# Pure value-object domain: frozen data records with few/no methods are expected.
+min-public-methods = 0
+max-args = 6

dispatch_kit-0.1.0/setup.cfg

@@ -0,0 +1,9 @@
+[flake8]
+max-line-length = 100
+extend-ignore = E203, W503
+exclude = .venv,.git,__pycache__,build,dist
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

dispatch_kit-0.1.0/src/dispatch_kit/__init__.py

@@ -0,0 +1,88 @@
+"""dispatch-kit — a pure, fail-closed library for gating expensive remote/external work.
+
+Decide whether an expensive operation may run, how much it will cost, and where it should run —
+the same machinery for a cloud GPU job (Cloud Run L4 over a tailnet) and a paid LLM/SDK API call:
+
+    from dispatch_kit import BudgetCap, BudgetState, admits, estimate_cost  # the hard $ cap
+    from dispatch_kit import select_backend, BackendKind, ToolRequirements  # where it runs
+    from dispatch_kit import SecretRef, ExternalEndpoint, log_egress  # opt-in API egress
+    from dispatch_kit import Approval  # the approval audit fact
+
+Pure domain — stdlib only, no I/O, no provider SDK code; every check is fail-closed (default budget
+``0`` = paid work off; SDK egress opt-in only; a missing key/over-budget refuses). The transport
+auth (who) is a separate concern — pair this with ``tailnet-guard``. The consuming app keeps its job
+entity, persistence, and executor; this owns the policy.
+"""
+
+from __future__ import annotations
+
+from .approval import Approval, ApprovalOutcome
+from .budget import (
+    AdmissionDecision,
+    BudgetCap,
+    BudgetState,
+    BudgetWindow,
+    CostRates,
+    admits,
+    estimate_cost,
+)
+from .dispatch import (
+    DispatchError,
+    JobStore,
+    Lease,
+    Transport,
+    WorkerExecutor,
+    is_lease_stale,
+    should_give_up,
+)
+from .egress import (
+    EnvLookup,
+    ExternalEndpoint,
+    SecretMissingError,
+    SecretRef,
+    log_egress,
+)
+from .estimate import CostEstimate, HostCapabilities, vram_fits
+from .routing import (
+    BackendCapabilities,
+    BackendKind,
+    NodeIdentity,
+    NoEligibleBackendError,
+    Routable,
+    ToolRequirements,
+    select_backend,
+)
+
+__all__ = [
+    "AdmissionDecision",
+    "Approval",
+    "ApprovalOutcome",
+    "BackendCapabilities",
+    "BackendKind",
+    "BudgetCap",
+    "BudgetState",
+    "BudgetWindow",
+    "CostEstimate",
+    "CostRates",
+    "DispatchError",
+    "EnvLookup",
+    "ExternalEndpoint",
+    "HostCapabilities",
+    "JobStore",
+    "Lease",
+    "NoEligibleBackendError",
+    "NodeIdentity",
+    "Routable",
+    "SecretMissingError",
+    "SecretRef",
+    "ToolRequirements",
+    "Transport",
+    "WorkerExecutor",
+    "admits",
+    "estimate_cost",
+    "is_lease_stale",
+    "log_egress",
+    "select_backend",
+    "should_give_up",
+    "vram_fits",
+]

dispatch_kit-0.1.0/src/dispatch_kit/approval.py

@@ -0,0 +1,44 @@
+"""Approval — the human decision + audit record that gates an expensive (non-local) job.
+
+A gated job leaves "awaiting approval" only by a human decision; recording WHO decided, WHEN, and
+WHY keeps a paid run attributable (append-only in spirit). The state machine — which states are
+gated and the transitions between them — lives in the consuming app's job entity; this is the
+shared audit fact and the binary outcome both apps record.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+
+
+class ApprovalOutcome(enum.StrEnum):
+    """The decision a human made on a gated job."""
+
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+
+@dataclass(frozen=True, slots=True)
+class Approval:
+    """Who approved or rejected a gated job, when, and why — the audit fact.
+
+    ``author``/``reason``/``decided_at`` are all required: a decision is never anonymous,
+    unexplained, or untimestamped. ``decided_at`` is ISO-8601, server-assigned at the decision.
+    ``outcome`` defaults to APPROVED so the common "approve" path constructs positionally; a
+    rejection passes ``ApprovalOutcome.REJECTED``.
+    """
+
+    author: str
+    reason: str
+    decided_at: str
+    outcome: ApprovalOutcome = ApprovalOutcome.APPROVED
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("author", self.author),
+            ("reason", self.reason),
+            ("decided_at", self.decided_at),
+        ):
+            if not value:
+                raise ValueError(f"an approval needs a non-empty {name}")

dispatch_kit-0.1.0/src/dispatch_kit/budget.py

@@ -0,0 +1,156 @@
+"""Budget ledger — a hard, fail-closed spend cap that gates expensive (non-local) work.
+
+Cloud GPU jobs and paid API calls cost real money, so a **hard** spend cap is a circuit breaker
+against errant testing or an agent flooding dispatch. The cap is enforced by **reserving** a job's
+upper-bound cost the moment it is approved/queued, against BOTH a per-run window and a per-month
+window: a job is admitted only if ``reserved + spent + its estimate`` stays within both caps. A
+burst of approvals reserves cumulatively, so once a cap is reached the next job is refused — you
+cannot even *queue* past it. The default cap is **zero**, so paid work stays off until you
+deliberately set a budget.
+
+This is pure domain (the rule); the persisted ledger rows + the per-backend rates live in the
+consuming app's storage layer. Money is a :class:`~decimal.Decimal` (exact), never a float — a
+fraction of a cent per GPU-second compounds, and a cost guard that drifts is not a guard.
+"""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from decimal import Decimal
+
+
+class BudgetWindow(enum.StrEnum):
+    """The windows a reservation is checked against — BOTH must have room (fail closed).
+
+    ``RUN`` bounds a single batch/session (stops one runaway loop); ``MONTH`` bounds slow
+    accumulation across sessions. A job must fit under both to be admitted.
+    """
+
+    RUN = "run"
+    MONTH = "month"
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetCap:
+    """The hard ceiling per window, in USD. Default ``0`` means paid work is OFF (fail closed)."""
+
+    run_usd: Decimal = Decimal(0)
+    month_usd: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        if self.run_usd < 0 or self.month_usd < 0:
+            raise ValueError("a budget cap cannot be negative")
+
+    def for_window(self, window: BudgetWindow) -> Decimal:
+        """The cap for ``window`` (the single source the admission rule reads)."""
+        return self.run_usd if window is BudgetWindow.RUN else self.month_usd
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetState:
+    """Committed USD for a window: ``reserved`` (approved, not yet run) + ``spent`` (reconciled).
+
+    Reserving on approval and only reconciling ``reserved -> spent`` on completion is what makes a
+    burst of approvals count immediately — the cap sees the whole queue's cost, not just what ran.
+    """
+
+    reserved_usd: Decimal = Decimal(0)
+    spent_usd: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        if self.reserved_usd < 0 or self.spent_usd < 0:
+            raise ValueError("budget reserved/spent cannot be negative")
+
+    def committed(self) -> Decimal:
+        """The total already committed against the cap (reserved + spent)."""
+        return self.reserved_usd + self.spent_usd
+
+
+@dataclass(frozen=True, slots=True)
+class CostRates:
+    """Per-second USD rates for a backend — plain config data (no provider SDK code here).
+
+    ``idle_tail_s`` is the post-request warm tail you still pay (a GPU Cloud Run instance bills for
+    ~10 min after the last request before scaling to zero); folding it into the estimate keeps the
+    reservation an upper bound. A token-priced API can model itself with ``gpu_usd_per_s`` = 0 and a
+    flat per-call cost via :func:`estimate_cost` inputs, or extend this with its own rate object.
+    """
+
+    gpu_usd_per_s: Decimal
+    vcpu_usd_per_s: Decimal
+    gib_usd_per_s: Decimal
+    idle_tail_s: Decimal = Decimal(0)
+
+    def __post_init__(self) -> None:
+        for name, value in (
+            ("gpu_usd_per_s", self.gpu_usd_per_s),
+            ("vcpu_usd_per_s", self.vcpu_usd_per_s),
+            ("gib_usd_per_s", self.gib_usd_per_s),
+            ("idle_tail_s", self.idle_tail_s),
+        ):
+            if value < 0:
+                raise ValueError(f"{name} cannot be negative")
+
+
+@dataclass(frozen=True, slots=True)
+class AdmissionDecision:
+    """Whether a job fits the budget, and — when it does not — which window refused and why.
+
+    ``refused_window`` is the first window (run, then month) that lacked room; ``None`` on admit.
+    The reason is human-facing, so the refusal is legible at approval, never a silent drop.
+    """
+
+    admitted: bool
+    refused_window: BudgetWindow | None
+    reason: str
+
+
+def admits(
+    estimate_usd: Decimal,
+    run_state: BudgetState,
+    month_state: BudgetState,
+    cap: BudgetCap,
+) -> AdmissionDecision:
+    """Can a job whose upper-bound cost is ``estimate_usd`` be admitted? Fail-closed, both windows.
+
+    Admitted only if ``reserved + spent + estimate <= cap`` for the run AND the month window. The
+    default cap (zero) admits nothing — paid work stays off until a budget is set. A negative
+    estimate is refused (its cost is not reasoned about); a zero-cost job within a zero cap is fine.
+    """
+    if estimate_usd < 0:
+        return AdmissionDecision(False, None, "a cost estimate cannot be negative")
+    for window, state in ((BudgetWindow.RUN, run_state), (BudgetWindow.MONTH, month_state)):
+        cap_window = cap.for_window(window)
+        if state.committed() + estimate_usd > cap_window:
+            return AdmissionDecision(
+                False,
+                window,
+                (
+                    f"would exceed the {window.value} budget cap (${cap_window}): "
+                    f"${state.committed()} committed + ${estimate_usd} estimate"
+                ),
+            )
+    return AdmissionDecision(True, None, "within budget")
+
+
+def estimate_cost(
+    rates: CostRates,
+    *,
+    max_runtime_s: int,
+    vcpus: int,
+    memory_gib: int,
+) -> Decimal:
+    """Upper-bound USD for one job: (max runtime + idle tail) x (GPU + vCPU + memory) rates. Pure.
+
+    Uses the caller's declared MAX runtime plus the warm idle tail, so the reservation
+    over-estimates; the ledger reconciles ``reserved -> spent`` from the backend's true reported
+    runtime on completion. Over-reserving is the safe direction for a hard cap.
+    """
+    if max_runtime_s < 0 or vcpus < 0 or memory_gib < 0:
+        raise ValueError("runtime/vcpus/memory cannot be negative")
+    billable_s = Decimal(max_runtime_s) + rates.idle_tail_s
+    per_second = (
+        rates.gpu_usd_per_s + rates.vcpu_usd_per_s * vcpus + rates.gib_usd_per_s * memory_gib
+    )
+    return billable_s * per_second

dispatch_kit-0.1.0/src/dispatch_kit/dispatch.py

@@ -0,0 +1,102 @@
+"""Dispatch contract for expensive async jobs that run anywhere on the tailnet.
+
+Both a PULL worker (it polls: claim a job, run it, complete it) and a PUSH orchestrator (it posts a
+job to a worker and waits) need the SAME guarantees: a job is CLAIMED atomically so it runs exactly
+once, a stale result is REJECTED, and a worker that dies mid-job has its lease RECOVERED. This
+module is the shared CONTRACT — the pure lease rules + the store/transport/worker protocols. The
+store (SQLite vs SQLAlchemy), the transport (pull vs push), and the payload (a transcribe request vs
+a tool invocation) are per-app ADAPTERS, so two apps converge on one model WITHOUT a shared DB.
+
+Auth (who may run a job) is :mod:`tailnet_guard`; policy (afford / route / approve) is the rest of
+:mod:`dispatch_kit`. This is only the run-it-once-recoverably engine on top of those.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+class DispatchError(RuntimeError):
+    """A dispatch invariant was violated (a stale complete, or a job recovered past its cap)."""
+
+
+@dataclass(frozen=True, slots=True)
+class Lease:
+    """A claim on a job: when it was leased and how many times it has been recovered.
+
+    ``leased_at`` is epoch seconds, stamped at the atomic claim. ``attempts`` counts recoveries (a
+    worker that died and had its lease reclaimed); a job past ``max_attempts`` fails rather than
+    re-leasing forever.
+    """
+
+    job_id: str
+    leased_at: float
+    attempts: int = 0
+
+
+def is_lease_stale(leased_at: float, now: float, ttl_seconds: float) -> bool:
+    """Whether a lease has outlived its TTL (the worker likely died) and may be reclaimed.
+
+    The single home of the lease-staleness rule, shared by every store's ``recover_stale`` so a
+    "leased but silent" job is reclaimed on one schedule. ``ttl_seconds`` should comfortably exceed
+    the longest a healthy run takes, so a slow job is not stolen from a live worker.
+    """
+    return (now - leased_at) >= ttl_seconds
+
+
+def should_give_up(attempts: int, max_attempts: int) -> bool:
+    """Whether a job has been recovered too many times and should FAIL rather than re-lease.
+
+    Fail-closed against a poison job that crashes every worker it lands on: after ``max_attempts``
+    recoveries it is marked failed (with its recorded error), never re-queued indefinitely.
+    """
+    return attempts >= max_attempts
+
+
+class JobStore(Protocol):
+    """The authoritative job store — the ONE place a job's claim/complete is decided, ATOMICALLY.
+
+    ``claim`` must be atomic (one transaction / compare-and-set): two concurrent workers can never
+    both claim the same job — that single claim is the run-exactly-once guarantee. ``complete`` must
+    REJECT a result for a job not currently leased/running (a stale resubmit after the lease was
+    recovered), returning ``False`` so a re-run cannot clobber a fresh result. ``recover_stale``
+    re-leases jobs whose lease outlived the TTL (see :func:`is_lease_stale`), bumping the attempt
+    count and failing a job past ``max_attempts`` (see :func:`should_give_up`). The payload type is
+    the app's own (a transcribe request, a tool invocation, ...).
+    """
+
+    def claim(self, lanes: Sequence[str]) -> tuple[str, Any] | None:
+        """Atomically claim ONE runnable job in ``lanes`` -> ``(job_id, payload)``, or ``None``."""
+
+    def complete(self, job_id: str, result: Any) -> bool:
+        """Apply a result IFF the job is leased/running; ``False`` if stale (done/recovered)."""
+
+    def recover_stale(self, *, now: float, ttl_seconds: float, max_attempts: int) -> Sequence[str]:
+        """Re-lease jobs whose lease is stale (return their ids); fail those past the cap."""
+
+
+class Transport(Protocol):
+    """The hop that moves a job to where it runs — the only thing that differs push vs pull.
+
+    PULL: the worker calls the store's claim/complete directly, so there is no Transport. PUSH: the
+    orchestrator submits the encoded job to a worker endpoint and gets the encoded result back.
+    Either way the worker's auth (``tailnet_guard``) and the policy are unchanged — this is
+    purely the byte-moving seam, so an app swaps pull for push without touching its job model.
+    """
+
+    def submit(self, envelope: dict[str, Any], token: str) -> dict[str, Any]:
+        """Deliver an encoded job to a worker with its capability token; return the response."""
+
+
+class WorkerExecutor(Protocol):
+    """The worker-side run contract: decode (integrity-checked) -> run -> encode.
+
+    The decode MUST verify every artifact's content hash, and the run happens only AFTER the auth
+    guard passes (guard-before-decode), so a tampered/unauthorized job never reaches the executor.
+    Returns the encoded result the store/transport carries back.
+    """
+
+    def execute(self, payload: Any) -> Any:
+        """Run an already-authorized, integrity-checked payload and return its encoded result."""