mundane-sdk 0.0.2__tar.gz

mundane_sdk-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Bellamy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mundane_sdk-0.0.2/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: mundane-sdk
+Version: 0.0.2
+Summary: Tiny durable-execution: one workflow run is one SQLite file.
+Author: Paul Bellamy
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paulbellamy/mundane
+Project-URL: Repository, https://github.com/paulbellamy/mundane
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mundane (Python)
+
+See [`../SPEC.md`](../SPEC.md) for the cross-runtime contract.
+
+```python
+import mundane
+
+def workflow(ctx):
+    user = ctx.step("fetch", lambda: {"name": "alice"})
+    ctx.sleep("cool-off", "100ms")
+    ctx.step("notify", lambda: f"hi {user['name']}")
+
+mundane.run("task.db", workflow)
+```
+
+An async variant is available: `await mundane.arun(path, async_workflow)`
+with `await ctx.astep(...)` / `await ctx.asleep(...)`.
+
+## Implementation notes
+
+- **Stdlib only.** No third-party dependencies — `sqlite3`, `fcntl`
+  (for `flock`), `json`, and `uuid` from the standard library.

mundane_sdk-0.0.2/README.md

@@ -0,0 +1,22 @@
+# mundane (Python)
+
+See [`../SPEC.md`](../SPEC.md) for the cross-runtime contract.
+
+```python
+import mundane
+
+def workflow(ctx):
+    user = ctx.step("fetch", lambda: {"name": "alice"})
+    ctx.sleep("cool-off", "100ms")
+    ctx.step("notify", lambda: f"hi {user['name']}")
+
+mundane.run("task.db", workflow)
+```
+
+An async variant is available: `await mundane.arun(path, async_workflow)`
+with `await ctx.astep(...)` / `await ctx.asleep(...)`.
+
+## Implementation notes
+
+- **Stdlib only.** No third-party dependencies — `sqlite3`, `fcntl`
+  (for `flock`), `json`, and `uuid` from the standard library.

mundane_sdk-0.0.2/mundane/__init__.py

@@ -0,0 +1,26 @@
+"""mundane — tiny durable-execution library.
+
+One workflow run is one SQLite file. Crash, re-invoke, resume.
+"""
+
+from .core import (
+    DuplicateStepError,
+    LockedError,
+    SchemaError,
+    SerializationError,
+    StepFailedError,
+    arun,
+    run,
+)
+
+__all__ = [
+    "run",
+    "arun",
+    "LockedError",
+    "SerializationError",
+    "SchemaError",
+    "StepFailedError",
+    "DuplicateStepError",
+]
+
+__version__ = "0.0.2"

mundane_sdk-0.0.2/mundane/_duration.py

@@ -0,0 +1,38 @@
+"""Parse human-friendly duration strings.
+
+Accepts strings like "30s", "5m", "2h", "1d", "500ms", or ints/floats in
+seconds (matching neither TS nor JS conventions strictly — the TS API
+documents number-of-milliseconds, the Python API documents number-of-seconds).
+For consistency with the TS interface, we accept both: strings and numbers
+where numbers are treated as milliseconds when called from the public API
+(see core.py).
+
+This module only parses strings and returns milliseconds.
+"""
+
+import re
+
+_UNIT_MS = {
+    "ms": 1,
+    "s": 1000,
+    "m": 60 * 1000,
+    "h": 60 * 60 * 1000,
+    "d": 24 * 60 * 60 * 1000,
+}
+
+# Matches: "5m", "1h", "2.5s", "500ms". Allow integer or decimal magnitudes.
+_RE = re.compile(r"^\s*(\d+(?:\.\d+)?)(ms|s|m|h|d)\s*$", re.IGNORECASE)
+
+
+def parse_duration_ms(s: str) -> int:
+    """Parse a duration string into integer milliseconds."""
+    if not isinstance(s, str):
+        raise TypeError(f"duration must be a string, got {type(s).__name__}")
+    m = _RE.match(s)
+    if not m:
+        raise ValueError(
+            f"invalid duration {s!r}: expected e.g. '500ms', '30s', '5m', '2h', '1d'"
+        )
+    magnitude = float(m.group(1))
+    unit = m.group(2).lower()
+    return int(round(magnitude * _UNIT_MS[unit]))

mundane_sdk-0.0.2/mundane/_lock.py

@@ -0,0 +1,48 @@
+"""Exclusive file locking via flock(2).
+
+Per spec section 3: the runtime acquires flock(LOCK_EX | LOCK_NB) on the
+SQLite file's fd. On failure, fail-fast with exit code 75 / LockedError.
+
+Note: flock(2) and POSIX record locks (used internally by SQLite) live in
+separate lock-spaces on Linux, so an flock on the DB file does not interfere
+with SQLite's own locking.
+"""
+
+import contextlib
+import fcntl
+import os
+from typing import Optional
+
+
+class FileLock:
+    """An exclusive non-blocking flock held for the lifetime of the object."""
+
+    def __init__(self, path: str):
+        self.path = path
+        self._fd: Optional[int] = None
+
+    def acquire(self) -> None:
+        # Open for read+write, creating if missing. SQLite will also open it
+        # later; that's fine.
+        fd = os.open(self.path, os.O_RDWR | os.O_CREAT, 0o644)
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            os.close(fd)
+            raise
+        self._fd = fd
+
+    def release(self) -> None:
+        if self._fd is not None:
+            with contextlib.suppress(OSError):
+                fcntl.flock(self._fd, fcntl.LOCK_UN)
+            with contextlib.suppress(OSError):
+                os.close(self._fd)
+            self._fd = None
+
+    def __enter__(self) -> "FileLock":
+        self.acquire()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.release()

mundane_sdk-0.0.2/mundane/_schema.py

@@ -0,0 +1,44 @@
+"""Schema definition shared across mundane runtimes.
+
+The schema is pinned to v1. Opening a file whose meta.schema_version is
+not '1' is a hard error.
+"""
+
+import re
+
+SCHEMA_VERSION = "1"
+
+# Name regex per spec section 5: ^[A-Za-z0-9][A-Za-z0-9._-]*$
+NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-]*$")
+
+
+BOOTSTRAP_SQL = """
+PRAGMA journal_mode = DELETE;
+
+CREATE TABLE IF NOT EXISTS mundane_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS mundane_steps (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  name         TEXT NOT NULL,
+  kind         TEXT NOT NULL,
+  encoding     TEXT NOT NULL,
+  result       BLOB,
+  status       TEXT NOT NULL,
+  error        TEXT,
+  started_at   TEXT NOT NULL,
+  finished_at  TEXT,
+  UNIQUE(name)
+);
+
+CREATE INDEX IF NOT EXISTS mundane_steps_status ON mundane_steps(status);
+"""
+
+
+def validate_name(name: str) -> None:
+    if not isinstance(name, str) or not NAME_RE.match(name):
+        raise ValueError(
+            f"invalid step name {name!r}: must match {NAME_RE.pattern}"
+        )

mundane_sdk-0.0.2/mundane/core.py

@@ -0,0 +1,437 @@
+"""Core implementation: run, ctx.step, ctx.sleep."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sqlite3
+import time
+import urllib.parse
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Awaitable, Callable, Dict, Optional, Set, Union
+
+from ._duration import parse_duration_ms
+from ._lock import FileLock
+from ._schema import BOOTSTRAP_SQL, SCHEMA_VERSION, validate_name
+
+
+class LockedError(Exception):
+    """Raised when the SQLite file is locked by another live process."""
+
+
+class SerializationError(Exception):
+    """Raised when a step's return value doesn't survive a JSON round-trip."""
+
+
+class SchemaError(Exception):
+    """Raised when meta.schema_version doesn't equal 1."""
+
+
+class DuplicateStepError(Exception):
+    """Raised when the same step name is used twice in one task body."""
+
+    def __init__(self, name: str):
+        super().__init__(f"duplicate step name: {name}")
+        self.name = name
+
+
+class StepFailedError(Exception):
+    """Raised when a step function raises. Wraps the underlying error."""
+
+    def __init__(self, name: str, original: BaseException):
+        super().__init__(f"step {name!r} failed: {original!r}")
+        self.name = name
+        self.original = original
+
+
+def _iso_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def _duration_to_ms(duration: Union[str, int, float]) -> int:
+    if isinstance(duration, str):
+        return parse_duration_ms(duration)
+    if isinstance(duration, (int, float)):
+        return int(duration)
+    raise TypeError(f"duration must be str or number, got {type(duration).__name__}")
+
+
+def _check_json_roundtrip(value: Any) -> str:
+    """Validate that value survives JSON.dumps -> JSON.loads -> deep equal.
+
+    Per spec section 7: catches Date, undefined, BigInt, Map, Set, functions,
+    and circular refs. Returns the JSON text on success.
+    """
+    try:
+        text = json.dumps(value, allow_nan=False)
+    except (TypeError, ValueError) as e:
+        raise SerializationError(str(e)) from None
+
+    decoded = json.loads(text)
+    if not _deep_equal(value, decoded):
+        raise SerializationError(
+            "value does not round-trip through JSON "
+            "(possibly contains tuples, sets, dates, or other non-JSON types)"
+        )
+    return text
+
+
+def _deep_equal(a: Any, b: Any) -> bool:
+    """Strict structural equality across JSON-shaped values."""
+    if type(a) is not type(b):
+        # Allow int/float boundary if numerically equal? No — strict, since
+        # JSON.dumps preserves int vs float in Python (json emits 1 vs 1.0).
+        return False
+    if isinstance(a, dict):
+        if a.keys() != b.keys():
+            return False
+        return all(_deep_equal(a[k], b[k]) for k in a)
+    if isinstance(a, list):
+        if len(a) != len(b):
+            return False
+        return all(_deep_equal(x, y) for x, y in zip(a, b))
+    return a == b
+
+
+@dataclass
+class _StepRow:
+    id: int
+    name: str
+    kind: str
+    encoding: str
+    result: Optional[bytes]
+    status: str
+    error: Optional[str]
+
+
+def _decode_result(row: _StepRow) -> Any:
+    if row.status != "done":
+        raise RuntimeError(
+            f"internal: step {row.name!r} not done (status={row.status})"
+        )
+    enc = row.encoding
+    raw = row.result
+    if raw is None:
+        return None
+    # v1.1: only json (structured + sleep wake-times) and bytes (raw payloads).
+    if enc == "json":
+        text = raw.decode("utf-8") if isinstance(raw, bytes) else raw
+        return json.loads(text)
+    if enc == "bytes":
+        return raw if isinstance(raw, bytes) else raw.encode("utf-8")
+    raise RuntimeError(f"unknown encoding: {enc!r}")
+
+
+class _Task:
+    """Per-invocation task state: open connection, cache, seen-name set."""
+
+    def __init__(self, conn: sqlite3.Connection):
+        self.conn = conn
+        # cache: name -> _StepRow
+        self.cache: Dict[str, _StepRow] = {}
+        # Per-run set of step names already used; duplicates raise.
+        self.seen: Set[str] = set()
+        self._load_cache()
+
+    def _load_cache(self) -> None:
+        cur = self.conn.execute(
+            "SELECT id, name, kind, encoding, result, status, error "
+            "FROM mundane_steps ORDER BY id"
+        )
+        for row in cur:
+            sr = _StepRow(
+                id=row[0],
+                name=row[1],
+                kind=row[2],
+                encoding=row[3],
+                result=row[4],
+                status=row[5],
+                error=row[6],
+            )
+            self.cache[sr.name] = sr
+
+    def _check_seen(self, name: str) -> None:
+        if name in self.seen:
+            raise DuplicateStepError(name)
+        self.seen.add(name)
+
+    def _ensure_pending_row(self, name: str, kind: str, encoding: str) -> _StepRow:
+        """Insert a pending row if not present; return the (possibly fresh) row.
+
+        A leftover pending/failed row (never 'done' on this path) is reset to
+        pending so the on-disk state reflects the retry, not a stale failure.
+        """
+        existing = self.cache.get(name)
+        if existing is not None:
+            self.conn.execute(
+                "UPDATE mundane_steps "
+                "SET kind=?, encoding=?, status='pending', result=NULL, error=NULL, finished_at=NULL "
+                "WHERE name=?",
+                (kind, encoding, name),
+            )
+            self.conn.commit()
+            existing.kind = kind
+            existing.encoding = encoding
+            existing.status = "pending"
+            existing.result = None
+            existing.error = None
+            return existing
+        now = _iso_now()
+        self.conn.execute(
+            "INSERT INTO mundane_steps "
+            "(name, kind, encoding, result, status, started_at) "
+            "VALUES (?, ?, ?, NULL, 'pending', ?)",
+            (name, kind, encoding, now),
+        )
+        self.conn.commit()
+        # Re-load row to get id
+        cur = self.conn.execute(
+            "SELECT id, name, kind, encoding, result, status, error "
+            "FROM mundane_steps WHERE name = ?",
+            (name,),
+        )
+        row = cur.fetchone()
+        sr = _StepRow(
+            id=row[0], name=row[1], kind=row[2], encoding=row[3],
+            result=row[4], status=row[5], error=row[6],
+        )
+        self.cache[name] = sr
+        return sr
+
+    def _commit_done(self, name: str, encoding: str, result: Any) -> None:
+        """Mark a step done with the given (already-encoded) result bytes/text."""
+        finished = _iso_now()
+        self.conn.execute(
+            "UPDATE mundane_steps "
+            "SET status = 'done', encoding = ?, result = ?, finished_at = ?, error = NULL "
+            "WHERE name = ?",
+            (encoding, result, finished, name),
+        )
+        self.conn.commit()
+        # Refresh cache
+        row = self.cache[name]
+        row.status = "done"
+        row.encoding = encoding
+        row.result = result if isinstance(result, (bytes, bytearray)) else (
+            result.encode("utf-8") if isinstance(result, str) else result
+        )
+
+    def _commit_failed(self, name: str, error: str) -> None:
+        finished = _iso_now()
+        self.conn.execute(
+            "UPDATE mundane_steps "
+            "SET status = 'failed', error = ?, finished_at = ? "
+            "WHERE name = ?",
+            (error, finished, name),
+        )
+        self.conn.commit()
+        row = self.cache.get(name)
+        if row is not None:
+            row.status = "failed"
+            row.error = error
+
+
+class Context:
+    """The object passed to a workflow body. Provides step() and sleep()."""
+
+    def __init__(self, task: _Task):
+        self._task = task
+
+    def step(self, name: str, fn: Callable[[], Any]) -> Any:
+        validate_name(name)
+        self._task._check_seen(name)
+        resolved = name
+        row = self._task.cache.get(resolved)
+        if row is not None and row.status == "done":
+            return _decode_result(row)
+        # pending or absent: ensure row, run fn, commit
+        self._task._ensure_pending_row(resolved, "step", "json")
+        try:
+            value = fn()
+        except Exception as e:
+            self._task._commit_failed(resolved, repr(e))
+            raise StepFailedError(resolved, e) from e
+        text = _check_json_roundtrip(value)
+        self._task._commit_done(resolved, "json", text)
+        # Return the round-tripped value so first run and resume agree exactly.
+        return json.loads(text)
+
+    def sleep(self, name: str, duration: Union[str, int, float]) -> None:
+        validate_name(name)
+        self._task._check_seen(name)
+        resolved = name
+        row = self._task.cache.get(resolved)
+        if row is not None and row.status == "done":
+            # Resume: duration arg is ignored (SPEC §6); don't parse it.
+            wake_at = _decode_result(row)
+            self._sleep_remaining(int(wake_at))
+            return
+        # absent / pending: compute wake_at, write json-number row, sleep.
+        wake_at = _now_ms() + _duration_to_ms(duration)
+        self._task._ensure_pending_row(resolved, "sleep", "json")
+        self._task._commit_done(resolved, "json", str(wake_at))
+        self._sleep_remaining(wake_at)
+
+    def _sleep_remaining(self, wake_at_ms: int) -> None:
+        now = _now_ms()
+        remaining = wake_at_ms - now
+        if remaining > 0:
+            time.sleep(remaining / 1000.0)
+
+    # ---- async variants ----
+
+    async def astep(self, name: str, fn: Callable[[], Awaitable[Any]]) -> Any:
+        validate_name(name)
+        self._task._check_seen(name)
+        resolved = name
+        row = self._task.cache.get(resolved)
+        if row is not None and row.status == "done":
+            return _decode_result(row)
+        self._task._ensure_pending_row(resolved, "step", "json")
+        try:
+            value = await fn()
+        except Exception as e:
+            self._task._commit_failed(resolved, repr(e))
+            raise StepFailedError(resolved, e) from e
+        text = _check_json_roundtrip(value)
+        self._task._commit_done(resolved, "json", text)
+        # Return the round-tripped value so first run and resume agree exactly.
+        return json.loads(text)
+
+    async def asleep(self, name: str, duration: Union[str, int, float]) -> None:
+        validate_name(name)
+        self._task._check_seen(name)
+        resolved = name
+        row = self._task.cache.get(resolved)
+        if row is not None and row.status == "done":
+            # Resume: duration arg is ignored (SPEC §6); don't parse it.
+            wake_at = int(_decode_result(row))
+        else:
+            wake_at = _now_ms() + _duration_to_ms(duration)
+            self._task._ensure_pending_row(resolved, "sleep", "json")
+            self._task._commit_done(resolved, "json", str(wake_at))
+        remaining = wake_at - _now_ms()
+        if remaining > 0:
+            await asyncio.sleep(remaining / 1000.0)
+
+
+def _open_task(path: str) -> tuple[FileLock, sqlite3.Connection, _Task]:
+    """Acquire lock, open DB, bootstrap schema, build cache. Caller owns cleanup."""
+    lock = FileLock(path)
+    try:
+        lock.acquire()
+    except BlockingIOError:
+        raise LockedError(
+            f"{path}: locked by another process"
+        ) from None
+
+    conn: Optional[sqlite3.Connection] = None
+    try:
+        # vfs=unix-none disables SQLite's own file locking. Mundane already
+        # holds an exclusive flock(2) on the file for the whole run, so
+        # SQLite's internal locking is redundant — and on macOS, where
+        # SQLite's POSIX locks share state with our flock on the same vnode,
+        # leaving it on would deadlock against ourselves ("database is
+        # locked"). The flock above is the sole writer-lock authority.
+        # quote() with safe="/" preserves path separators but escapes ? & %
+        # so paths with those characters don't break URI parsing.
+        encoded = urllib.parse.quote(path, safe="/")
+        conn = sqlite3.connect(
+            f"file:{encoded}?vfs=unix-none", uri=True, isolation_level=None
+        )
+        conn.execute("PRAGMA journal_mode = DELETE")
+
+        # Pre-check: if mundane_meta already exists with a non-1 schema_version,
+        # bail before running CREATE INDEX (which references columns we don't
+        # promise on other schema versions).
+        existing = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='mundane_meta'"
+        ).fetchone()
+        if existing:
+            row = conn.execute(
+                "SELECT value FROM mundane_meta WHERE key='schema_version'"
+            ).fetchone()
+            if row and row[0] != SCHEMA_VERSION:
+                raise SchemaError(
+                    f"{path}: schema_version is {row[0]!r}, expected {SCHEMA_VERSION!r}"
+                )
+
+        # Bootstrap inside an IMMEDIATE transaction (idempotent).
+        conn.execute("BEGIN IMMEDIATE")
+        try:
+            statements = [s.strip() for s in BOOTSTRAP_SQL.split(";") if s.strip()]
+            for stmt in statements:
+                conn.execute(stmt)
+            now_iso = _iso_now()
+            new_uuid = str(uuid.uuid4())
+            conn.execute(
+                "INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('schema_version', ?)",
+                (SCHEMA_VERSION,),
+            )
+            conn.execute(
+                "INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('task_id', ?)",
+                (new_uuid,),
+            )
+            conn.execute(
+                "INSERT OR IGNORE INTO mundane_meta (key, value) VALUES ('created_at', ?)",
+                (now_iso,),
+            )
+            conn.execute("COMMIT")
+        except Exception:
+            conn.execute("ROLLBACK")
+            raise
+
+        # Final schema-version check (covers the fresh-bootstrap path).
+        row = conn.execute(
+            "SELECT value FROM mundane_meta WHERE key = 'schema_version'"
+        ).fetchone()
+        if not row or row[0] != SCHEMA_VERSION:
+            raise SchemaError(
+                f"{path}: schema_version is {row[0] if row else None!r}, expected {SCHEMA_VERSION!r}"
+            )
+
+        task = _Task(conn)
+        return lock, conn, task
+    except Exception:
+        if conn is not None:
+            conn.close()
+        lock.release()
+        raise
+
+
+def run(path: str, fn: Callable[[Context], Any]) -> Any:
+    """Run a workflow body against the SQLite file at `path`.
+
+    On cache miss, fn-passed step closures execute; on cache hit they return
+    the cached value without re-executing. Returns fn's return value.
+
+    Raises LockedError if another process holds the file lock.
+    """
+    lock, conn, task = _open_task(path)
+    try:
+        ctx = Context(task)
+        return fn(ctx)
+    finally:
+        try:
+            conn.close()
+        finally:
+            lock.release()
+
+
+async def arun(path: str, fn: Callable[[Context], Awaitable[Any]]) -> Any:
+    """Async variant of run(). The body can use ctx.astep / ctx.asleep."""
+    lock, conn, task = _open_task(path)
+    try:
+        ctx = Context(task)
+        return await fn(ctx)
+    finally:
+        try:
+            conn.close()
+        finally:
+            lock.release()

mundane_sdk-0.0.2/mundane_sdk.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: mundane-sdk
+Version: 0.0.2
+Summary: Tiny durable-execution: one workflow run is one SQLite file.
+Author: Paul Bellamy
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/paulbellamy/mundane
+Project-URL: Repository, https://github.com/paulbellamy/mundane
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mundane (Python)
+
+See [`../SPEC.md`](../SPEC.md) for the cross-runtime contract.
+
+```python
+import mundane
+
+def workflow(ctx):
+    user = ctx.step("fetch", lambda: {"name": "alice"})
+    ctx.sleep("cool-off", "100ms")
+    ctx.step("notify", lambda: f"hi {user['name']}")
+
+mundane.run("task.db", workflow)
+```
+
+An async variant is available: `await mundane.arun(path, async_workflow)`
+with `await ctx.astep(...)` / `await ctx.asleep(...)`.
+
+## Implementation notes
+
+- **Stdlib only.** No third-party dependencies — `sqlite3`, `fcntl`
+  (for `flock`), `json`, and `uuid` from the standard library.

mundane_sdk-0.0.2/mundane_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+mundane/__init__.py
+mundane/_duration.py
+mundane/_lock.py
+mundane/_schema.py
+mundane/core.py
+mundane_sdk.egg-info/PKG-INFO
+mundane_sdk.egg-info/SOURCES.txt
+mundane_sdk.egg-info/dependency_links.txt
+mundane_sdk.egg-info/top_level.txt
+tests/test_basic.py

mundane_sdk-0.0.2/mundane_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mundane_sdk-0.0.2/mundane_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+mundane

mundane_sdk-0.0.2/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mundane-sdk"
+version = "0.0.2"
+description = "Tiny durable-execution: one workflow run is one SQLite file."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Paul Bellamy" }]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/paulbellamy/mundane"
+Repository = "https://github.com/paulbellamy/mundane"
+
+[tool.setuptools.packages.find]
+include = ["mundane*"]

mundane_sdk-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mundane_sdk-0.0.2/tests/test_basic.py

@@ -0,0 +1,303 @@
+"""Basic tests for mundane (Python)."""
+
+import asyncio
+import contextlib
+import json
+import multiprocessing as mp
+import os
+import sqlite3
+import sys
+import tempfile
+import time
+import unittest
+
+# Make the package importable without installation.
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import mundane
+
+
+def _hold_lock_child(path, barrier, done):
+    # Module-scope helper for test_second_process_gets_locked_error.
+    # Must be picklable for multiprocessing's spawn start method (default on
+    # macOS), so it can't be a local closure inside the test method.
+    def wf(ctx):
+        ctx.step("a", lambda: 1)
+        barrier.set()
+        done.wait(timeout=5)
+        return 0
+
+    mundane.run(path, wf)
+
+
+def _names(path):
+    """Step names in id order, read straight from SQLite (no inspect API)."""
+    conn = sqlite3.connect(path)
+    try:
+        return [r[0] for r in conn.execute(
+            "SELECT name FROM mundane_steps ORDER BY id"
+        )]
+    finally:
+        conn.close()
+
+
+class TempDB:
+    def __enter__(self):
+        self.fd, self.path = tempfile.mkstemp(suffix=".db")
+        os.close(self.fd)
+        os.remove(self.path)  # mundane will recreate
+        return self.path
+
+    def __exit__(self, *_):
+        for ext in ("", "-wal", "-shm", ".lock"):
+            with contextlib.suppress(FileNotFoundError):
+                os.remove(self.path + ext)
+
+
+class HappyPath(unittest.TestCase):
+    def test_three_steps_run_once(self):
+        calls = []
+
+        def wf(ctx):
+            a = ctx.step("a", lambda: (calls.append("a"), 1)[1])
+            b = ctx.step("b", lambda: (calls.append("b"), {"v": a + 1})[1])
+            return b
+
+        with TempDB() as path:
+            r = mundane.run(path, wf)
+            self.assertEqual(r, {"v": 2})
+            self.assertEqual(calls, ["a", "b"])
+
+            # Re-run: should return same value without re-calling
+            r2 = mundane.run(path, wf)
+            self.assertEqual(r2, {"v": 2})
+            self.assertEqual(calls, ["a", "b"])  # not re-called
+
+    def test_resume_after_crash(self):
+        """Simulate crash by raising after step 1; verify step 1 is cached."""
+        with TempDB() as path:
+            # First run: succeed step a, raise before step b commits
+            def wf1(ctx):
+                ctx.step("a", lambda: 42)
+                raise RuntimeError("simulated crash")
+
+            with self.assertRaises(RuntimeError):
+                mundane.run(path, wf1)
+
+            # Second run: step a returns 42 from cache; step b runs and finishes.
+            calls = []
+
+            def wf2(ctx):
+                v = ctx.step("a", lambda: (calls.append("a"), 999)[1])
+                w = ctx.step("b", lambda: (calls.append("b"), v + 1)[1])
+                return w
+
+            r = mundane.run(path, wf2)
+            self.assertEqual(r, 43)
+            self.assertEqual(calls, ["b"])  # only b was called; a came from cache
+
+
+class Naming(unittest.TestCase):
+    def test_invalid_name_rejected(self):
+        with TempDB() as path:
+            def wf(ctx):
+                ctx.step("bad name with space", lambda: 1)
+            with self.assertRaises(ValueError):
+                mundane.run(path, wf)
+
+    def test_duplicate_name_raises(self):
+        with TempDB() as path:
+            def wf(ctx):
+                ctx.step("x", lambda: 1)
+                ctx.step("x", lambda: 2)  # duplicate -> raises
+            with self.assertRaises(mundane.DuplicateStepError):
+                mundane.run(path, wf)
+            # First step still committed before the duplicate was raised.
+            self.assertEqual(_names(path), ["x"])
+
+
+class Locking(unittest.TestCase):
+    def test_second_process_gets_locked_error(self):
+        with TempDB() as path:
+            barrier = mp.Event()
+            done = mp.Event()
+
+            proc = mp.Process(target=_hold_lock_child, args=(path, barrier, done))
+            proc.start()
+            try:
+                barrier.wait(timeout=5)
+                # Try to open while the other process holds the lock.
+                with self.assertRaises(mundane.LockedError):
+                    mundane.run(path, lambda ctx: None)
+            finally:
+                done.set()
+                proc.join(timeout=5)
+
+
+class Sleep(unittest.TestCase):
+    def test_sleep_persists_wake_at_and_resumes(self):
+        with TempDB() as path:
+            # First "run": write the sleep row but interrupt before sleeping
+            # by using a 0ms duration.
+            t0 = time.time()
+            mundane.run(path, lambda ctx: ctx.sleep("nap", "10ms"))
+            elapsed1 = time.time() - t0
+            self.assertLess(elapsed1, 0.2)
+
+            # Second run: nap row already done; should return immediately.
+            t0 = time.time()
+            mundane.run(path, lambda ctx: ctx.sleep("nap", "10s"))
+            elapsed2 = time.time() - t0
+            self.assertLess(elapsed2, 0.2)
+
+    def test_resume_ignores_invalid_duration(self):
+        with TempDB() as path:
+            mundane.run(path, lambda ctx: ctx.sleep("n", "1ms"))
+            # Resume ignores the duration arg, so an invalid string is a no-op.
+            mundane.run(path, lambda ctx: ctx.sleep("n", "not-a-duration"))
+
+    def test_sleep_remaining_on_resume(self):
+        """If we crash mid-sleep, next run should sleep only the remaining time."""
+        with TempDB() as path:
+            # First run: writes wake_at = now + 200ms then sleeps the full 200ms.
+            # We use 50ms so the test is quick but observable.
+            t0 = time.time()
+            mundane.run(path, lambda ctx: ctx.sleep("n", "50ms"))
+            self.assertGreaterEqual(time.time() - t0, 0.04)
+
+    def test_resume_sleeps_only_the_remainder(self):
+        """A wake_at still in the future makes resume sleep the remainder."""
+        with TempDB() as path:
+            # Establish the sleep row with a short duration.
+            mundane.run(path, lambda ctx: ctx.sleep("n", "10ms"))
+            # Rewrite wake_at ~300ms into the future to simulate a long nap whose
+            # process was restarted before it elapsed.
+            future = int(time.time() * 1000) + 300
+            conn = sqlite3.connect(path)
+            conn.execute("UPDATE mundane_steps SET result=? WHERE name='n'", (str(future),))
+            conn.commit()
+            conn.close()
+            # Resume must block for the remaining ~300ms (duration arg ignored).
+            t0 = time.time()
+            mundane.run(path, lambda ctx: ctx.sleep("n", "10ms"))
+            self.assertGreaterEqual(time.time() - t0, 0.2)
+
+
+class FailedStep(unittest.TestCase):
+    def test_failed_step_reruns(self):
+        with TempDB() as path:
+            def boom():
+                raise RuntimeError("boom")
+
+            with self.assertRaises(mundane.StepFailedError):
+                mundane.run(path, lambda ctx: ctx.step("s", boom))
+
+            # A failed step is not cached; it must re-run.
+            calls = []
+            r = mundane.run(path, lambda ctx: ctx.step("s", lambda: (calls.append("s"), 7)[1]))
+            self.assertEqual(r, 7)
+            self.assertEqual(calls, ["s"])
+
+    def test_failed_row_reset_to_pending_during_rerun(self):
+        with TempDB() as path:
+            def boom():
+                raise RuntimeError("boom")
+
+            with self.assertRaises(mundane.StepFailedError):
+                mundane.run(path, lambda ctx: ctx.step("s", boom))
+
+            # While the re-run body executes, the row must read 'pending' with
+            # the stale error cleared (the reset committed before fn runs).
+            seen = {}
+
+            def observe():
+                # observe() runs inside mundane.run, while the writer holds
+                # an exclusive flock on the file. On macOS, opening with the
+                # default unix VFS would deadlock against that flock — open
+                # with unix-none (no SQLite-level lock) instead.
+                conn = sqlite3.connect(f"file:{path}?vfs=unix-none", uri=True)
+                seen["status"], seen["error"] = conn.execute(
+                    "SELECT status, error FROM mundane_steps WHERE name='s'"
+                ).fetchone()
+                conn.close()
+                return 7
+
+            mundane.run(path, lambda ctx: ctx.step("s", observe))
+            self.assertEqual(seen["status"], "pending")
+            self.assertIsNone(seen["error"])
+
+
+class Async(unittest.TestCase):
+    def test_arun_astep_asleep(self):
+        async def aval(calls, tag, v):
+            calls.append(tag)
+            return v
+
+        with TempDB() as path:
+            calls = []
+
+            async def wf(ctx):
+                a = await ctx.astep("a", lambda: aval(calls, "a", 1))
+                await ctx.asleep("nap", "10ms")
+                return await ctx.astep("b", lambda: aval(calls, "b", a + 1))
+
+            r = asyncio.run(mundane.arun(path, wf))
+            self.assertEqual(r, 2)
+            self.assertEqual(calls, ["a", "b"])
+
+            # Resume: both steps cache-hit, neither fn runs.
+            calls.clear()
+            r2 = asyncio.run(mundane.arun(path, wf))
+            self.assertEqual(r2, 2)
+            self.assertEqual(calls, [])
+
+
+class Inspect(unittest.TestCase):
+    def test_steps_committed(self):
+        with TempDB() as path:
+            def wf(ctx):
+                ctx.step("a", lambda: {"x": 1})
+                ctx.step("b", lambda: "hello")
+
+            mundane.run(path, wf)
+            # Inspection lives in the CLI now; verify on-disk state directly.
+            conn = sqlite3.connect(path)
+            done = conn.execute(
+                "SELECT COUNT(*) FROM mundane_steps WHERE status='done'"
+            ).fetchone()[0]
+            self.assertEqual(done, 2)
+            a = conn.execute(
+                "SELECT result, encoding FROM mundane_steps WHERE name='a'"
+            ).fetchone()
+            self.assertEqual(a[1], "json")
+            self.assertEqual(json.loads(a[0]), {"x": 1})
+            conn.close()
+
+
+class Serialization(unittest.TestCase):
+    def test_non_jsonable_raises(self):
+        with TempDB() as path:
+            def wf(ctx):
+                # Tuples become lists in JSON; that's a roundtrip mismatch.
+                ctx.step("a", lambda: (1, 2, 3))
+            with self.assertRaises(mundane.SerializationError):
+                mundane.run(path, wf)
+
+
+class Schema(unittest.TestCase):
+    def test_wrong_schema_version_rejected(self):
+        with TempDB() as path:
+            # Create a file with wrong schema version manually.
+            conn = sqlite3.connect(path)
+            conn.execute("CREATE TABLE mundane_meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)")
+            conn.execute("CREATE TABLE mundane_steps (id INTEGER PRIMARY KEY)")
+            conn.execute("INSERT INTO mundane_meta VALUES ('schema_version', '99')")
+            conn.commit()
+            conn.close()
+
+            with self.assertRaises(mundane.SchemaError):
+                mundane.run(path, lambda ctx: None)
+
+
+if __name__ == "__main__":
+    unittest.main()