durably 0.1.0__py3-none-any.whl

durably/__init__.py

@@ -0,0 +1,26 @@
+"""durably: durable execution for AI agents, with just Postgres."""
+
+from durably.activity_context import ActivityInfo, activity_info, heartbeat
+from durably.client import Client
+from durably.context import Context
+from durably.errors import (
+    ActivityError, NonDeterminismError, StaleWorkerError, WorkflowFailedError, WorkflowNotRunningError,
+)
+from durably.registry import activity, workflow
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    # Imported lazily so `python -m durably.worker` does not load the module twice.
+    if name in ("ActivityWorker", "WorkflowWorker"):
+        from durably import worker
+        return getattr(worker, name)
+    raise AttributeError(f"module 'durably' has no attribute {name!r}")
+
+__all__ = [
+    "ActivityError", "ActivityInfo", "ActivityWorker", "Client", "Context", "NonDeterminismError",
+    "StaleWorkerError", "WorkflowFailedError", "WorkflowNotRunningError", "WorkflowWorker",
+    "activity", "activity_info",
+    "heartbeat", "workflow",
+]

durably/activity_context.py

@@ -0,0 +1,55 @@
+"""What a running activity can see and do: its own info, and heartbeats."""
+
+from contextvars import ContextVar
+from dataclasses import dataclass
+from typing import Any
+
+import asyncpg
+
+from durably import store
+from durably.errors import StaleWorkerError
+
+
+@dataclass(frozen=True)
+class ActivityInfo:
+    workflow_id: str
+    name: str
+    idempotency_key: str
+    attempt: int
+    heartbeat_details: Any  # last details saved by a previous attempt, or None
+
+
+@dataclass(frozen=True)
+class _Running:
+    info: ActivityInfo
+    pool: asyncpg.Pool
+    claim: store.Claim
+    worker_id: str
+    lease_s: float
+
+
+_current: ContextVar[_Running] = ContextVar("durably_activity")
+
+
+def _running() -> _Running:
+    try:
+        return _current.get()
+    except LookupError:
+        raise RuntimeError("only available inside a running activity") from None
+
+
+def activity_info() -> ActivityInfo:
+    return _running().info
+
+
+async def heartbeat(details: Any = None) -> None:
+    """Tell durably this activity is still alive, optionally saving progress.
+
+    Extends the lease by the activity's heartbeat timeout. If the activity is retried,
+    the next attempt sees the last `details` in `activity_info().heartbeat_details`.
+    Raises StaleWorkerError if the task was already handed to another worker; stop work.
+    """
+    run = _running()
+    async with run.pool.acquire() as conn:
+        if not await store.heartbeat(conn, run.claim, run.worker_id, run.lease_s, details):
+            raise StaleWorkerError("activity lease lost: another worker owns this task now")

durably/cli.py

@@ -0,0 +1,41 @@
+"""`durably` command-line entry point."""
+
+import argparse
+import asyncio
+import logging
+
+from durably import worker
+from durably.db import connect, init_db
+
+
+async def _init_db(url: str | None) -> None:
+    conn = await connect(url)
+    try:
+        await init_db(conn)
+    finally:
+        await conn.close()
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(prog="durably")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    init = sub.add_parser("init-db", help="create durably's tables in Postgres")
+    init.add_argument("--database-url", default=None, help="defaults to $DATABASE_URL")
+
+    worker.add_arguments(sub.add_parser("worker", help="run a workflow or activity worker"))
+
+    args = parser.parse_args(argv)
+    if args.command == "init-db":
+        asyncio.run(_init_db(args.database_url))
+        print("durably: schema ready")
+    elif args.command == "worker":
+        logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s %(message)s")
+        try:
+            asyncio.run(worker.serve(args))
+        except KeyboardInterrupt:
+            pass
+
+
+if __name__ == "__main__":
+    main()

durably/client.py

@@ -0,0 +1,104 @@
+"""Client API: start workflows and wait for their results."""
+
+import asyncio
+from collections.abc import Callable
+from typing import Any
+
+import asyncpg
+
+from durably import registry, store
+from durably.db import create_pool
+from durably.errors import WorkflowFailedError, WorkflowNotRunningError
+
+
+class Client:
+    def __init__(self, pool: asyncpg.Pool):
+        self.pool = pool
+        self._owns_pool = False
+
+    @classmethod
+    async def connect(cls, url: str | None = None) -> "Client":
+        client = cls(await create_pool(url))
+        client._owns_pool = True
+        return client
+
+    async def close(self) -> None:
+        if self._owns_pool:
+            await self.pool.close()
+
+    async def start(self, workflow: Callable | str, input: Any = None, idempotency_key: str | None = None) -> str:
+        """Start a workflow and return its id.
+
+        A second start with the same idempotency key returns the existing workflow's
+        id and starts nothing, even if `input` differs.
+        """
+        async with self.pool.acquire() as conn, conn.transaction():
+            wf_id = await store.create_workflow(conn, registry.name_of(workflow), input, idempotency_key=idempotency_key)
+            if wf_id is None:
+                return str(await conn.fetchval("SELECT id FROM workflows WHERE idempotency_key = $1", idempotency_key))
+        return str(wf_id)
+
+    async def signal(self, workflow_id: str, name: str, payload: Any = None) -> None:
+        """Send a signal to a running workflow; `ctx.wait_signal(name)` receives it.
+
+        The signal is recorded in the workflow's history before this returns, so it is not
+        lost if no worker is running. If the workflow continued as new, the signal goes to
+        its latest run. Raises WorkflowNotRunningError if the workflow has finished or does
+        not exist.
+        """
+        async with self.pool.acquire() as conn:
+            while True:
+                run = await store.latest_run(conn, workflow_id)
+                if run is None or run["status"] != "running":
+                    raise WorkflowNotRunningError(f"workflow {workflow_id} is not running")
+                tx = conn.transaction()
+                await tx.start()
+                if await store.deliver(conn, run["id"], "SignalReceived", {"name": name, "payload": payload}):
+                    await tx.commit()
+                    return
+                # The run finished or continued as new in the meantime: roll back the wake-up
+                # and look up the latest run again.
+                await tx.rollback()
+
+    async def describe(self, workflow_id: str) -> dict:
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT id, type, status, epoch, result, error, continued_as, created_at FROM workflows WHERE id = $1",
+                workflow_id,
+            )
+        if row is None:
+            raise LookupError(f"no workflow {workflow_id}")
+        return dict(row)
+
+    async def history(self, workflow_id: str) -> list[store.Event]:
+        async with self.pool.acquire() as conn:
+            return await store.load_history(conn, workflow_id)
+
+    async def runs(self, workflow_id: str) -> list[str]:
+        """Ids of every run of a workflow, oldest first (more than one after Continue-As-New)."""
+        async with self.pool.acquire() as conn:
+            ids, current = [], workflow_id
+            while current is not None:
+                ids.append(str(current))
+                current = await conn.fetchval("SELECT continued_as FROM workflows WHERE id = $1", current)
+        return ids
+
+    async def result(self, workflow_id: str, timeout: float | None = None, poll: float = 0.05) -> Any:
+        """Wait for the workflow to finish and return its result.
+
+        Follows Continue-As-New to the final run. Raises WorkflowFailedError if it failed,
+        TimeoutError if `timeout` passes first.
+        """
+        async def wait() -> Any:
+            while True:
+                async with self.pool.acquire() as conn:
+                    run = await store.latest_run(conn, workflow_id)
+                if run is None:
+                    raise LookupError(f"no workflow {workflow_id}")
+                if run["status"] == "completed":
+                    return run["result"]
+                if run["status"] in ("failed", "cancelled"):
+                    raise WorkflowFailedError(f"workflow {workflow_id} {run['status']}: {run['error']}")
+                await asyncio.sleep(poll)
+
+        return await asyncio.wait_for(wait(), timeout)

durably/context.py

@@ -0,0 +1,276 @@
+"""The replay engine.
+
+A workflow task reruns the workflow function from the top against its history. Each
+`ctx.*` call takes the next command position:
+
+- history has a command there: it must match the call (else NonDeterminismError); if
+  its result is recorded, return it without running anything (G3);
+- history is exhausted: this is a new command; record it. Commands that need a result
+  (activities, timers) then suspend; markers (`now`, `random`, `uuid4`) do not, so one
+  workflow task can record several new commands.
+
+Suspending raises `_Suspend`, which unwinds the function. Nothing stays parked in memory:
+the next event wakes a fresh replay.
+"""
+
+import json
+import random
+import uuid
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, NoReturn
+from uuid import UUID
+
+from durably.errors import ActivityError, NonDeterminismError
+from durably.store import Event
+
+COMMAND_TYPES = {"ActivityScheduled", "TimerStarted", "MarkerRecorded"}
+# Result event type -> payload field naming the command it answers.
+RESULT_TYPES = {"ActivityCompleted": "scheduled_seq", "ActivityFailed": "scheduled_seq", "TimerFired": "started_seq"}
+
+
+class _ContinueAsNew(BaseException):
+    def __init__(self, input: Any):
+        self.input = input
+
+
+class _Suspend(BaseException):
+    """Unwinds the workflow when it needs a result that is not in history yet.
+
+    A BaseException so that `except Exception` in workflow code does not swallow it.
+    """
+
+
+@dataclass
+class Command:
+    type: str
+    payload: dict
+
+
+def _normalize(value: Any) -> Any:
+    """What a value looks like after a round trip through jsonb, for comparing with history."""
+    return json.loads(json.dumps(value))
+
+
+DEFAULT_MAX_HISTORY = 1000
+
+
+class Context:
+    def __init__(self, workflow_id: UUID, history: list[Event], max_history: int = DEFAULT_MAX_HISTORY):
+        self.workflow_id = workflow_id
+        self.max_history = max_history
+        self._history_length = len(history)
+        self._last_seq = history[-1].seq if history else 0
+        self._commands = [e for e in history if e.type in COMMAND_TYPES]
+        self._results = {e.payload[field]: e for e in history if (field := RESULT_TYPES.get(e.type))}
+        self._signals: dict[str, list[Event]] = defaultdict(list)
+        for e in history:
+            if e.type == "SignalReceived":
+                self._signals[e.payload["name"]].append(e)
+        self._signals_taken: Counter[str] = Counter()
+        self._pos = 0
+        self.new_commands: list[Command] = []
+        self.nondeterminism: NonDeterminismError | None = None
+
+    def _command(self, type: str, payload: dict, identity: tuple[str, ...]) -> Event:
+        """Like `_take`, but a new command suspends the workflow until its result arrives."""
+        recorded = self._take(type, payload, identity)
+        if recorded is None:
+            raise _Suspend()
+        return recorded
+
+    def _take(self, type: str, payload: dict, identity: tuple[str, ...]) -> Event | None:
+        """Take the next command position and return the event history recorded there.
+
+        If history is exhausted, record `payload` as a new command and return None. If
+        history holds a different command (type or `identity` fields differ), the code
+        changed under a running workflow: raise NonDeterminismError (G5).
+        """
+        if self._pos >= len(self._commands):
+            self._pos += 1
+            self.new_commands.append(Command(type, payload))
+            return None
+        recorded = self._commands[self._pos]
+        expected = {k: recorded.payload.get(k) for k in identity}
+        actual = {k: payload[k] for k in identity}
+        if recorded.type != type or expected != actual:
+            # Remembered on the context too, so workflow code that catches broad
+            # exceptions cannot hide it.
+            self.nondeterminism = NonDeterminismError(
+                f"command {self._pos}: history has {recorded.type} "
+                f"{ {k: recorded.payload.get(k) for k in ('name', 'args', 'seconds', 'kind') if k in recorded.payload} }, "
+                f"code issued {type} {actual}"
+            )
+            raise self.nondeterminism
+        self._pos += 1
+        return recorded
+
+    async def activity(self, name: str, args: list | tuple = (), *, retry: dict | None = None,
+                       timeout: float | None = None, heartbeat_timeout: float | None = None) -> Any:
+        """Run an activity at least once and return its result (or raise ActivityError).
+
+        `timeout` limits one attempt. With `heartbeat_timeout`, an attempt that goes that
+        long without calling `durably.heartbeat()` is treated as hung and retried.
+        """
+        recorded = self._command("ActivityScheduled", {
+            "name": name, "args": _normalize(list(args)), "retry": retry, "timeout": timeout,
+            "heartbeat_timeout": heartbeat_timeout,
+        }, identity=("name", "args"))
+        outcome = self._results.get(recorded.seq)
+        if outcome is None:
+            raise _Suspend()  # scheduled, still running
+        if outcome.type == "ActivityFailed":
+            raise ActivityError(name, outcome.payload["error"])
+        return outcome.payload["result"]
+
+    async def sleep(self, seconds: float) -> None:
+        """Sleep durably: survives crashes, restarts and deploys.
+
+        The wake-up time is fixed when the timer is first recorded, on the database clock.
+        """
+        recorded = self._command("TimerStarted", {"seconds": float(seconds), "for_signal": None},
+                                 identity=("seconds", "for_signal"))
+        if recorded.seq not in self._results:
+            raise _Suspend()
+
+    def _marker(self, kind: str, make) -> Any:
+        """Return the value recorded for this marker, or record a fresh one from `make()`."""
+        recorded = self._take("MarkerRecorded", {"kind": kind, "value": None}, identity=("kind",))
+        if recorded is not None:
+            return recorded.payload["value"]
+        value = _normalize(make())
+        self.new_commands[-1].payload["value"] = value
+        return value
+
+    def now(self) -> datetime:
+        """The current UTC time, recorded the first time so every replay sees the same value."""
+        return datetime.fromisoformat(self._marker("now", lambda: datetime.now(timezone.utc).isoformat()))
+
+    def random(self) -> float:
+        """A random float in [0, 1), recorded so every replay sees the same value."""
+        return self._marker("random", random.random)
+
+    def uuid4(self) -> UUID:
+        """A random UUID, recorded so every replay sees the same value."""
+        return UUID(self._marker("uuid4", lambda: str(uuid.uuid4())))
+
+    def should_continue_as_new(self) -> bool:
+        """True once this run's history has reached `max_history` events.
+
+        Check it at a safe point (for example once per loop iteration) and call
+        `continue_as_new` when it is True, so replay time stays bounded. A True answer is
+        recorded as a marker, so replays answer exactly as the original run did.
+        """
+        nxt = self._commands[self._pos] if self._pos < len(self._commands) else None
+        if nxt is not None:  # replaying: True only where the original run recorded it
+            if nxt.type == "MarkerRecorded" and nxt.payload.get("kind") == "continue_as_new_suggested":
+                self._pos += 1
+                return True
+            return False
+        if self._history_length + len(self.new_commands) < self.max_history:
+            return False
+        self._take("MarkerRecorded", {"kind": "continue_as_new_suggested", "value": True}, identity=("kind",))
+        return True
+
+    def continue_as_new(self, input: Any) -> NoReturn:
+        """End this run and start a fresh one with `input` and an empty history.
+
+        Signals this run received but did not take are carried over to the new run, in
+        order. Clients holding the original id follow the chain automatically.
+        """
+        raise _ContinueAsNew(_normalize(input))
+
+    def _untaken_signals(self) -> list[dict]:
+        untaken = [e for name, events in self._signals.items() for e in events[self._signals_taken[name]:]]
+        return [e.payload for e in sorted(untaken, key=lambda e: e.seq)]
+
+    async def wait_signal(self, name: str, timeout: float | None = None) -> Any:
+        """Wait for the next signal called `name` and return its payload.
+
+        Signals are taken in the order they were sent, each exactly once (G8): the n-th
+        wait for `name` gets the n-th signal, on every replay. With `timeout`, returns None
+        if no signal arrives in time; a later signal then goes to the next wait.
+        """
+        n = self._signals_taken[name]
+        signals = self._signals[name]
+        signal = signals[n] if n < len(signals) else None
+
+        # A timed wait that found no signal yet started a timer. On replay, tell that apart
+        # from a wait that got its signal straight away: the timer is the next command and
+        # the signal (if any) arrived after it.
+        nxt = self._commands[self._pos] if self._pos < len(self._commands) else None
+        timer_was_started = (
+            timeout is not None and nxt is not None and nxt.type == "TimerStarted"
+            and nxt.payload.get("for_signal") == name and (signal is None or signal.seq > nxt.seq)
+        )
+        if not timer_was_started:
+            if signal is not None:
+                self._signals_taken[name] += 1
+                return signal.payload["payload"]
+            if timeout is None:
+                raise _Suspend()  # nothing to schedule; the signal itself wakes the workflow
+        assert timeout is not None  # a timer exists only for timed waits
+        timer = self._command("TimerStarted", {"seconds": float(timeout), "for_signal": name},
+                              identity=("seconds", "for_signal"))
+        fired = self._results.get(timer.seq)
+        if signal is not None and (fired is None or signal.seq < fired.seq):
+            self._signals_taken[name] += 1
+            return signal.payload["payload"]
+        if fired is not None:
+            return None  # timed out; this signal (if it comes) is left for the next wait
+        raise _Suspend()
+
+
+# Every outcome but NonDeterministic carries the new commands to append, in order.
+@dataclass
+class Completed:
+    result: Any
+    commands: list[Command] = field(default_factory=list)
+
+
+@dataclass
+class Failed:
+    error: str
+    commands: list[Command] = field(default_factory=list)
+
+
+@dataclass
+class Suspended:
+    commands: list[Command] = field(default_factory=list)  # empty: waiting on something already recorded
+
+
+@dataclass
+class ContinuedAsNew:
+    input: Any
+    signals: list[dict]  # untaken signal payloads to carry over, in order
+    seen_through: int  # last seq this replay saw; later signals are carried too
+    commands: list[Command] = field(default_factory=list)
+
+
+@dataclass
+class NonDeterministic:
+    error: str
+
+
+async def replay(fn, ctx: Context, input: Any) -> Completed | Failed | Suspended | ContinuedAsNew | NonDeterministic:
+    """Run the workflow function against history once and report how it stopped."""
+    outcome: Completed | Failed | Suspended | ContinuedAsNew | None
+    try:
+        result = await fn(ctx, input)
+    except _Suspend:
+        outcome = Suspended(ctx.new_commands)
+    except _ContinueAsNew as e:
+        outcome = ContinuedAsNew(e.input, ctx._untaken_signals(), ctx._last_seq, ctx.new_commands)
+    except Exception as e:
+        outcome = Failed(f"{type(e).__name__}: {e}", ctx.new_commands)
+    else:
+        outcome = None
+    if ctx.nondeterminism is not None:
+        return NonDeterministic(str(ctx.nondeterminism))
+    if outcome is not None:
+        return outcome
+    try:
+        return Completed(_normalize(result), ctx.new_commands)
+    except (TypeError, ValueError) as e:
+        return Failed(f"workflow result is not JSON-serializable: {e}", ctx.new_commands)

durably/db.py

@@ -0,0 +1,46 @@
+"""Database access: connection settings and schema setup."""
+
+import json
+import os
+from importlib.resources import files
+
+import asyncpg
+
+DEFAULT_URL = "postgres://durably:durably@localhost:5433/durably"
+
+# No database call waits forever: a connection that silently stops answering (a network
+# partition, a failed-over primary) raises TimeoutError, and the caller reconnects.
+DEFAULT_COMMAND_TIMEOUT_S = 60.0
+DEFAULT_CONNECT_TIMEOUT_S = 10.0
+
+
+def database_url() -> str:
+    return os.environ.get("DATABASE_URL", DEFAULT_URL)
+
+
+def schema_sql() -> str:
+    return files("durably").joinpath("schema.sql").read_text(encoding="utf-8")
+
+
+async def _init_connection(conn: asyncpg.Connection) -> None:
+    # jsonb columns round-trip as Python dicts/lists.
+    await conn.set_type_codec("jsonb", encoder=json.dumps, decoder=json.loads, schema="pg_catalog")
+
+
+async def connect(url: str | None = None, *, command_timeout: float = DEFAULT_COMMAND_TIMEOUT_S) -> asyncpg.Connection:
+    conn = await asyncpg.connect(url or database_url(), command_timeout=command_timeout,
+                                 timeout=DEFAULT_CONNECT_TIMEOUT_S)
+    await _init_connection(conn)
+    return conn
+
+
+async def create_pool(url: str | None = None, *, command_timeout: float = DEFAULT_COMMAND_TIMEOUT_S,
+                      **kwargs) -> asyncpg.Pool:
+    """A connection pool whose statements time out after `command_timeout` seconds."""
+    return await asyncpg.create_pool(url or database_url(), init=_init_connection, command_timeout=command_timeout,
+                                     timeout=min(command_timeout, DEFAULT_CONNECT_TIMEOUT_S), **kwargs)
+
+
+async def init_db(conn: asyncpg.Connection) -> None:
+    """Create tables, constraints and triggers. Idempotent."""
+    await conn.execute(schema_sql())

durably/errors.py

@@ -0,0 +1,30 @@
+"""Exceptions raised by durably."""
+
+
+class DurablyError(Exception):
+    pass
+
+
+class StaleWorkerError(DurablyError):
+    """This worker's epoch is no longer current; another worker owns the workflow."""
+
+
+class NonDeterminismError(DurablyError):
+    """Workflow code issued a different command than history recorded at this position."""
+
+
+class ActivityError(DurablyError):
+    """An activity failed after exhausting its retries. Raised inside the workflow."""
+
+    def __init__(self, name: str, message: str):
+        super().__init__(f"activity {name!r} failed: {message}")
+        self.name = name
+        self.message = message
+
+
+class WorkflowFailedError(DurablyError):
+    """Raised by `Client.result` when the workflow ended in failure."""
+
+
+class WorkflowNotRunningError(DurablyError):
+    """Raised by `Client.signal` when the workflow does not exist or has already finished."""

durably/failpoints.py

@@ -0,0 +1,42 @@
+"""Failpoints: make a worker die or freeze at a named point, for crash tests.
+
+`FAILPOINT=<name>` exits the process abruptly (no cleanup, no flush) the first time it
+reaches `<name>`; `FAILPOINT=<name>@<n>` waits for the n-th time. Adding `:pause`
+(`<name>:pause`, `<name>@<n>:pause`) stops it with SIGSTOP instead, so a test can let its
+lease expire and resume it later with SIGCONT (POSIX only).
+
+Points: `before_claim`, `after_claim`, `before_activity`, `after_effect_before_record`,
+`before_append`, `after_record_before_ack`, `during_timer_fire`.
+"""
+
+import os
+import signal
+from collections import Counter
+
+EXIT_CODE = 86
+
+_hits: Counter[str] = Counter()
+
+
+def parse(spec: str) -> tuple[str, int, str]:
+    """`name[@n][:action]` -> (name, n, action)."""
+    target, _, action = spec.partition(":")
+    name, _, nth = target.partition("@")
+    return name, int(nth or 1), action or "exit"
+
+
+def failpoint(name: str) -> None:
+    spec = os.environ.get("FAILPOINT")
+    if not spec:
+        return
+    target, nth, action = parse(spec)
+    if target != name:
+        return
+    _hits[name] += 1
+    if _hits[name] != nth:  # fire once, so a resumed worker carries on normally
+        return
+    os.write(2, f"durably: failpoint {name}@{nth} ({action}) pid {os.getpid()}\n".encode())
+    if action == "pause":
+        os.kill(os.getpid(), signal.SIGSTOP)
+    else:
+        os._exit(EXIT_CODE)

durably/registry.py

@@ -0,0 +1,44 @@
+"""`@workflow` and `@activity` decorators and the name -> function registry.
+
+Workers look functions up by name, so a workflow started by one process can be run by
+another that imported the same module.
+"""
+
+from collections.abc import Callable
+
+_workflows: dict[str, Callable] = {}
+_activities: dict[str, Callable] = {}
+
+
+def _register(table: dict[str, Callable], name: str | Callable | None):
+    def decorate(fn: Callable) -> Callable:
+        key = name if isinstance(name, str) else fn.__name__
+        setattr(fn, "__durably_name__", key)
+        table[key] = fn
+        return fn
+
+    if callable(name):  # used bare: @workflow
+        return decorate(name)
+    return decorate
+
+
+def workflow(name: str | Callable | None = None):
+    """Register `async def fn(ctx, input)` as a workflow."""
+    return _register(_workflows, name)
+
+
+def activity(name: str | Callable | None = None):
+    """Register `async def fn(*args, idempotency_key)` as an activity."""
+    return _register(_activities, name)
+
+
+def name_of(fn_or_name: Callable | str) -> str:
+    return fn_or_name if isinstance(fn_or_name, str) else getattr(fn_or_name, "__durably_name__")
+
+
+def get_workflow(name: str) -> Callable | None:
+    return _workflows.get(name)
+
+
+def get_activity(name: str) -> Callable | None:
+    return _activities.get(name)