sequentialist-core 0.1.0__py3-none-any.whl

sequentialist/core/sinks.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Sinks: where audit entries (decisions, alarms, actions) are announced.
+
+The audit log is the record; sinks are notifications.  The engine calls
+every sink with every new entry after the checkpoint that made it
+durable.  A failing sink is logged and never stops a task.  A webhook is
+sent from a background thread, with retries, so a slow receiver does not
+hold up the data.
+"""
+from __future__ import annotations
+
+import json
+import logging
+import queue
+import threading
+import time
+import urllib.request
+from pathlib import Path
+from typing import Callable, Dict, Sequence
+
+from .audit import AuditEntry
+
+logger = logging.getLogger("sequentialist")
+
+
+class LogSink:
+    """Logs entries of the given kinds (all but "created" and "segment" by default) as warnings."""
+
+    def __init__(self, kinds: Sequence[str] = ("decision", "action"), logger_name: str = "sequentialist"):
+        self.kinds, self.log = tuple(kinds), logging.getLogger(logger_name)
+
+    def __call__(self, entry: AuditEntry) -> None:
+        if entry.kind in self.kinds:
+            self.log.warning("%s %s: %s %s", entry.task_id, entry.kind, entry.decision or "", entry.basis)
+
+
+class JsonlSink:
+    """Appends every entry as a JSON line to a file."""
+
+    def __init__(self, path: str | Path):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+    def __call__(self, entry: AuditEntry) -> None:
+        line = json.dumps(entry.to_json(), sort_keys=True, ensure_ascii=False) + "\n"
+        with self._lock, open(self.path, "a", encoding="utf-8") as f:
+            f.write(line)
+
+
+Post = Callable[[str, bytes, Dict[str, str], float], None]
+
+
+def _post(url: str, body: bytes, headers: dict[str, str], timeout: float) -> None:
+    request = urllib.request.Request(url, data=body, headers=headers, method="POST")
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        response.read()
+
+
+class WebhookSink:
+    """POSTs entries of the given kinds as JSON; retries with exponential backoff, gives up after `attempts`."""
+
+    def __init__(self, url: str, *, kinds: Sequence[str] = ("decision", "action"), timeout: float = 5.0,
+                 attempts: int = 5, headers: dict[str, str] | None = None, post: Post | None = None):
+        self.url, self.kinds, self.timeout, self.attempts = url, tuple(kinds), float(timeout), int(attempts)
+        self.headers = {"Content-Type": "application/json", **(headers or {})}
+        self._post = post or _post
+        self._queue: queue.Queue = queue.Queue()
+        self._thread = threading.Thread(target=self._work, name="sequentialist-webhook", daemon=True)
+        self._thread.start()
+
+    def __call__(self, entry: AuditEntry) -> None:
+        if entry.kind in self.kinds:
+            self._queue.put(entry)
+
+    def _work(self) -> None:
+        while True:
+            entry = self._queue.get()
+            if entry is None:
+                return
+            body = json.dumps(entry.to_json()).encode("utf-8")
+            for attempt in range(self.attempts):
+                try:
+                    self._post(self.url, body, self.headers, self.timeout)
+                    break
+                except Exception as error:
+                    if attempt + 1 == self.attempts:
+                        logger.error("webhook %s: entry %d of task %s not delivered: %s", self.url, entry.n,
+                                     entry.task_id, error)
+                    else:
+                        time.sleep(min(60.0, 0.5 * 2**attempt))
+
+    def close(self, timeout: float = 10.0) -> None:
+        """Send what is queued, then stop."""
+        self._queue.put(None)
+        self._thread.join(timeout)

sequentialist/core/spec.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Specs: the declarative description of a task (an experiment, a monitor, a trial).
+
+A kind of spec is a subclass of `Spec` with a `kind` (``"ab.experiment/1"``:
+the name and the version of the format) and a `schema`.  Reading a spec
+checks it against the schema, then against the subclass's own rules
+(`problems`), and reports every error found at once, each with its JSON
+pointer::
+
+    spec = load_spec("experiment.yaml", ExperimentSpec)
+    spec.data          # the normal form: plain JSON, defaults filled in
+    spec_id(spec)      # SHA-256 of its canonical JSON
+
+JSON needs nothing; YAML needs PyYAML (``pip install "sequentialist-core[yaml]"``).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, ClassVar, Mapping, TypeVar
+
+from .canonical import digest
+from .errors import SpecError
+from .schema import INVALID, Errors, Field, Object, String
+
+S = TypeVar("S", bound="Spec")
+
+
+class Spec:
+    """Base class of every kind of spec.  Subclasses set `kind` and `schema` and may override `problems`."""
+
+    kind: ClassVar[str] = ""
+    schema: ClassVar[Object]
+
+    def __init__(self, data: dict[str, Any]):
+        """`data` is the normal form (as `parse_spec` returns it, without "kind")."""
+        self.data = data
+
+    def problems(self) -> list[tuple[str, str]]:
+        """Errors the schema cannot express (relations between members), as (JSON pointer, message)."""
+        return []
+
+    def to_json(self) -> dict[str, Any]:
+        return {"kind": self.kind, **self.data}
+
+    @property
+    def id(self) -> str:
+        """The spec id: SHA-256 of the canonical JSON of the normal form."""
+        return spec_id(self)
+
+
+def _full_schema(cls: type[Spec]) -> Object:
+    fields = {"kind": Field(String(enum=[cls.kind]), doc=f'The format of the spec: "{cls.kind}".')}
+    fields.update(cls.schema.fields)
+    return Object(fields, doc=cls.schema.doc)
+
+
+def parse_spec(data: Any, cls: type[S], source: str = "") -> S:
+    """A spec of kind `cls` from parsed JSON or YAML; SpecError lists every problem."""
+    errors: Errors = []
+    if isinstance(data, dict) and data.get("kind") != cls.kind:
+        errors.append(("/kind", f"expected {cls.kind!r}, got {data.get('kind')!r}"))
+        raise SpecError(errors, source)
+    normal = _full_schema(cls).check(data, "", errors)
+    if errors or normal is INVALID:
+        raise SpecError(errors, source)
+    del normal["kind"]
+    spec = cls(normal)
+    errors = list(spec.problems())
+    if errors:
+        raise SpecError(errors, source)
+    return spec
+
+
+def read_document(source: str | Path) -> Any:
+    """Parse a JSON or YAML file (by its extension) into plain values."""
+    path = Path(source)
+    text = path.read_text(encoding="utf-8")
+    if path.suffix.lower() in (".yaml", ".yml"):
+        try:
+            import yaml  # type: ignore[import-untyped]
+        except ImportError:
+            raise SpecError([("", "reading YAML needs PyYAML: pip install \"sequentialist-core[yaml]\"")],
+                            str(path)) from None
+        try:
+            return yaml.safe_load(text)
+        except yaml.YAMLError as error:
+            raise SpecError([("", f"not valid YAML: {error}")], str(path)) from None
+    try:
+        return json.loads(text, parse_constant=_no_constant)
+    except ValueError as error:
+        raise SpecError([("", f"not valid JSON: {error}")], str(path)) from None
+
+
+def _no_constant(name: str) -> Any:
+    raise ValueError(f"{name} is not a JSON number")
+
+
+def load_spec(source: str | Path | Mapping[str, Any], cls: type[S]) -> S:
+    """A spec from a file (.json, .yaml, .yml) or from an already parsed mapping."""
+    if isinstance(source, Mapping):
+        return parse_spec(dict(source), cls)
+    return parse_spec(read_document(source), cls, str(source))
+
+
+def spec_id(spec: Spec) -> str:
+    return digest(spec.to_json())
+
+
+def json_schema(cls: type[Spec]) -> dict[str, Any]:
+    """JSON Schema (draft 2020-12) of the spec format: for editors, other languages and validators."""
+    out = _full_schema(cls).json_schema()
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$id": f"https://github.com/andre-a-no/sequentialist/schemas/{cls.kind.replace('/', '-')}.schema.json",
+        "title": cls.kind,
+        **out,
+    }

sequentialist/core/storage/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Storages of tasks: in memory, in a directory of files, in SQLite.  Postgres follows in a later version."""
+from __future__ import annotations
+
+from .base import Storage, check_task_id
+from .files import FileStorage
+from .memory import MemoryStorage
+from .sqlite import SQLiteStorage
+
+__all__ = ["FileStorage", "MemoryStorage", "SQLiteStorage", "Storage", "check_task_id", "open_storage"]
+
+
+def open_storage(url: str, *, sync: str = "fsync") -> Storage:
+    """A storage from a short description: ``memory:``, ``files:<directory>`` or ``sqlite:<file>``."""
+    kind, _, where = url.partition(":")
+    if kind == "memory" and not where:
+        return MemoryStorage()
+    if kind == "files" and where:
+        return FileStorage(where, sync=sync)
+    if kind == "sqlite" and where:
+        return SQLiteStorage(where, sync=sync)
+    raise ValueError(f"unknown storage {url!r}: use memory:, files:<directory> or sqlite:<file>")

sequentialist/core/storage/_lock.py

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Exclusive locks on files, released by the operating system when the process ends.
+
+A crashed writer leaves no stale lock behind.  Two opens of the same lock
+file conflict even within one process, so a task cannot be opened twice by
+mistake either.
+"""
+from __future__ import annotations
+
+import os
+import sys
+import threading
+
+from ..errors import TaskLocked
+
+if sys.platform == "win32":  # pragma: no cover - exercised on Windows only
+    import msvcrt
+
+    def _try_lock(fd: int) -> bool:
+        try:
+            msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+        except OSError:
+            return False
+        return True
+
+    def _unlock(fd: int) -> None:
+        os.lseek(fd, 0, os.SEEK_SET)
+        msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+else:
+    import fcntl
+
+    def _try_lock(fd: int) -> bool:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            return False
+        return True
+
+    def _unlock(fd: int) -> None:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+class Lock:
+    """Held from creation until `release`."""
+
+    def release(self) -> None:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+    def __enter__(self) -> Lock:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.release()
+
+
+class FileLock(Lock):
+    def __init__(self, path: str, what: str):
+        self.path = path
+        fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o644)
+        if not _try_lock(fd):
+            os.close(fd)
+            raise TaskLocked(f"{what} is open in another writer (lock {path})")
+        self._fd: int = fd
+
+    def release(self) -> None:
+        if self._fd >= 0:
+            try:
+                _unlock(self._fd)
+            finally:
+                os.close(self._fd)
+                self._fd = -1
+
+
+class MemoryLock(Lock):
+    """A lock among the users of one object in one process (for in-memory storage)."""
+
+    def __init__(self, held: set[str], guard: threading.Lock, key: str, what: str):
+        with guard:
+            if key in held:
+                raise TaskLocked(f"{what} is open in another writer")
+            held.add(key)
+        self._held, self._guard, self._key = held, guard, key
+        self._released = False
+
+    def release(self) -> None:
+        with self._guard:
+            if not self._released:
+                self._held.discard(self._key)
+                self._released = True

sequentialist/core/storage/base.py

@@ -0,0 +1,102 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""What the engine needs from a storage, and the rules every storage follows.
+
+Per task a storage keeps:
+
+state      one JSON document with a version number.  `save` replaces it only
+           if the stored version is the one the writer read (`expected`),
+           so a second writer cannot silently overwrite the first;
+journal    JSON entries appended since the last checkpoint: what arrived,
+           written before it is processed;
+audit      JSON entries appended forever: the decisions and actions;
+documents  named JSON documents: archived segments, reports.
+
+A task has one writer at a time: `lock` raises TaskLocked while another
+holds it.  Values must be plain JSON (`sequentialist.core.canonical.is_plain`).
+"""
+from __future__ import annotations
+
+import re
+from abc import ABC, abstractmethod
+from typing import Any, Sequence
+
+from ..errors import StorageError
+from ._lock import Lock
+
+TASK_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}")
+DOCUMENT_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}(/[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}){0,7}")
+
+
+def check_task_id(task_id: str) -> str:
+    if not isinstance(task_id, str) or not TASK_ID.fullmatch(task_id):
+        raise StorageError(f"task id {task_id!r}: letters, digits, '_', '.' and '-' only, at most 128 characters, "
+                           f"not starting with '.', '_' or '-' (it names files)")
+    return task_id
+
+
+def check_document_name(name: str) -> str:
+    if not isinstance(name, str) or not DOCUMENT_NAME.fullmatch(name) or ".." in name:
+        raise StorageError(f"document name {name!r}: path segments of letters, digits, '_', '.', ':' and '-'")
+    return name
+
+
+class Storage(ABC):
+    @abstractmethod
+    def lock(self, task_id: str) -> Lock:
+        """Become the only writer of the task until the lock is released; TaskLocked otherwise."""
+
+    @abstractmethod
+    def tasks(self) -> list[str]:
+        """The ids of the stored tasks, sorted."""
+
+    @abstractmethod
+    def load(self, task_id: str) -> tuple[int, dict[str, Any]] | None:
+        """(version, state), or None if the task has never been saved."""
+
+    @abstractmethod
+    def save(self, task_id: str, state: dict[str, Any], *, expected: int, clear_journal: bool = False) -> int:
+        """Replace the state if the stored version is `expected` (0: none yet); return the new version.
+
+        With `clear_journal` the journal is emptied as well: atomically with
+        the state where the storage can (SQLite), right after it otherwise.
+        ConflictError if the version differs.
+        """
+
+    @abstractmethod
+    def journal_append(self, task_id: str, entries: Sequence[dict[str, Any]]) -> None:
+        """Append entries; they are on disk (per the storage's sync mode) when this returns."""
+
+    @abstractmethod
+    def journal_read(self, task_id: str) -> list[dict[str, Any]]:
+        """The entries appended since the journal was last cleared, in order."""
+
+    @abstractmethod
+    def audit_append(self, task_id: str, entry: dict[str, Any]) -> None:
+        """Append one audit entry; it is on disk when this returns."""
+
+    @abstractmethod
+    def audit_read(self, task_id: str) -> list[dict[str, Any]]:
+        """Every audit entry of the task, in order."""
+
+    @abstractmethod
+    def put_document(self, task_id: str, name: str, document: dict[str, Any]) -> None:
+        """Store (or replace) a named document."""
+
+    @abstractmethod
+    def get_document(self, task_id: str, name: str) -> dict[str, Any] | None:
+        """The named document, or None."""
+
+    @abstractmethod
+    def documents(self, task_id: str) -> list[str]:
+        """Names of the task's documents, sorted."""
+
+    def close(self) -> None:  # noqa: B027 - optional
+        """Release resources (connections, files)."""
+
+    def __enter__(self) -> Storage:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

sequentialist/core/storage/files.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""Storage in a directory: one subdirectory per task, plain JSON files.
+
+    <root>/<task>/state.json        {"format", "version", "state"}, replaced atomically
+    <root>/<task>/journal.jsonl     one entry per line
+    <root>/<task>/audit.jsonl       one entry per line
+    <root>/<task>/documents/...     one JSON file per document
+    <root>/<task>/.lock             held by the writer
+
+A crash in the middle of an append leaves a torn last line; it is ignored
+when reading and cut off by the next append.  `sync="fsync"` (the default)
+forces every append and state to the disk, so they survive a power
+failure; `sync="flush"` survives a crash of the process only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Sequence
+
+from ..canonical import loads
+from ..errors import ConflictError, StorageError
+from ._lock import FileLock, Lock
+from .base import Storage, check_document_name, check_task_id
+
+FORMAT = "sequentialist.files/1"
+
+
+def _fsync_directory(directory: Path) -> None:
+    if os.name != "posix":
+        return
+    fd = os.open(str(directory), os.O_RDONLY)
+    try:
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+
+
+def write_json_atomically(path: Path, value: Any, sync: bool = True) -> None:
+    """Write a file so that a crash leaves either the old content or the new one."""
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=path.name, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(value, f, sort_keys=True, ensure_ascii=False)
+            f.flush()
+            if sync:
+                os.fsync(f.fileno())
+        os.replace(tmp, str(path))
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    if sync:
+        _fsync_directory(path.parent)
+
+
+def _read_lines(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    out = []
+    with open(path, "rb") as f:
+        for number, line in enumerate(f, 1):
+            if not line.endswith(b"\n"):
+                break  # a torn last line: the append it belonged to never completed
+            try:
+                out.append(loads(line.decode("utf-8")))
+            except ValueError as error:
+                raise StorageError(f"{path}:{number}: not valid JSON ({error})") from None
+    return out
+
+
+class FileStorage(Storage):
+    def __init__(self, root: str | Path, *, sync: str = "fsync"):
+        if sync not in ("fsync", "flush"):
+            raise ValueError("sync must be 'fsync' or 'flush'")
+        self.root = Path(root)
+        self.sync = sync
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    def _dir(self, task_id: str, create: bool = False) -> Path:
+        directory = self.root / check_task_id(task_id)
+        if create:
+            (directory / "documents").mkdir(parents=True, exist_ok=True)
+        return directory
+
+    def lock(self, task_id: str) -> Lock:
+        return FileLock(str(self._dir(task_id, create=True) / ".lock"), f"task {task_id!r} in {self.root}")
+
+    def tasks(self) -> list[str]:
+        return sorted(p.name for p in self.root.iterdir() if (p / "state.json").exists())
+
+    def load(self, task_id: str) -> tuple[int, dict[str, Any]] | None:
+        path = self._dir(task_id) / "state.json"
+        if not path.exists():
+            return None
+        try:
+            stored = loads(path.read_text(encoding="utf-8"))
+        except ValueError as error:
+            raise StorageError(f"{path}: not valid JSON ({error})") from None
+        if not isinstance(stored, dict) or stored.get("format") != FORMAT or type(stored.get("version")) is not int:
+            raise StorageError(f"{path}: not a state file of this storage")
+        return stored["version"], stored["state"]
+
+    def save(self, task_id: str, state: dict[str, Any], *, expected: int, clear_journal: bool = False) -> int:
+        directory = self._dir(task_id, create=True)
+        loaded = self.load(task_id)
+        current = 0 if loaded is None else loaded[0]
+        if current != expected:
+            raise ConflictError(f"task {task_id!r}: stored version {current}, expected {expected}")
+        write_json_atomically(directory / "state.json", {"format": FORMAT, "version": current + 1, "state": state},
+                              self.sync == "fsync")
+        if clear_journal:
+            journal = directory / "journal.jsonl"
+            if journal.exists():
+                with open(journal, "r+b") as f:
+                    f.truncate(0)
+                    f.flush()
+                    if self.sync == "fsync":
+                        os.fsync(f.fileno())
+        return current + 1
+
+    def _append(self, path: Path, entries: Sequence[dict[str, Any]]) -> None:
+        data = b"".join((json.dumps(e, sort_keys=True, ensure_ascii=False) + "\n").encode("utf-8") for e in entries)
+        with open(path, "a+b") as f:
+            size = f.seek(0, os.SEEK_END)
+            if size:
+                f.seek(size - 1)
+                if f.read(1) != b"\n":  # a torn last line: cut it back to the last complete one
+                    f.seek(0)
+                    keep = f.read().rfind(b"\n") + 1
+                    f.truncate(keep)
+            f.write(data)
+            f.flush()
+            if self.sync == "fsync":
+                os.fsync(f.fileno())
+
+    def journal_append(self, task_id: str, entries: Sequence[dict[str, Any]]) -> None:
+        if entries:
+            self._append(self._dir(task_id, create=True) / "journal.jsonl", entries)
+
+    def journal_read(self, task_id: str) -> list[dict[str, Any]]:
+        return _read_lines(self._dir(task_id) / "journal.jsonl")
+
+    def audit_append(self, task_id: str, entry: dict[str, Any]) -> None:
+        self._append(self._dir(task_id, create=True) / "audit.jsonl", [entry])
+
+    def audit_read(self, task_id: str) -> list[dict[str, Any]]:
+        return _read_lines(self._dir(task_id) / "audit.jsonl")
+
+    def _document_path(self, task_id: str, name: str) -> Path:
+        return self._dir(task_id) / "documents" / (check_document_name(name) + ".json")
+
+    def put_document(self, task_id: str, name: str, document: dict[str, Any]) -> None:
+        self._dir(task_id, create=True)
+        path = self._document_path(task_id, name)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        write_json_atomically(path, document, self.sync == "fsync")
+
+    def get_document(self, task_id: str, name: str) -> dict[str, Any] | None:
+        path = self._document_path(task_id, name)
+        if not path.exists():
+            return None
+        found: dict[str, Any] = loads(path.read_text(encoding="utf-8"))
+        return found
+
+    def documents(self, task_id: str) -> list[str]:
+        base = self._dir(task_id) / "documents"
+        if not base.exists():
+            return []
+        return sorted(p.relative_to(base).as_posix()[:-5] for p in base.rglob("*.json"))

sequentialist/core/storage/memory.py

@@ -0,0 +1,64 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright (C) 2026 Novikov Laboratories LLC
+# Commercial licenses for use outside the AGPL: see COMMERCIAL.md
+"""In-memory storage: for simulations, replays and tests.  Nothing survives the process."""
+from __future__ import annotations
+
+import copy
+import threading
+from typing import Any, Sequence
+
+from ..errors import ConflictError
+from ._lock import Lock, MemoryLock
+from .base import Storage, check_document_name, check_task_id
+
+
+class MemoryStorage(Storage):
+    def __init__(self) -> None:
+        self._states: dict[str, tuple[int, dict[str, Any]]] = {}
+        self._journals: dict[str, list[dict[str, Any]]] = {}
+        self._audits: dict[str, list[dict[str, Any]]] = {}
+        self._documents: dict[str, dict[str, dict[str, Any]]] = {}
+        self._held: set[str] = set()
+        self._guard = threading.Lock()
+
+    def lock(self, task_id: str) -> Lock:
+        return MemoryLock(self._held, self._guard, check_task_id(task_id), f"task {task_id!r}")
+
+    def tasks(self) -> list[str]:
+        return sorted(self._states)
+
+    def load(self, task_id: str) -> tuple[int, dict[str, Any]] | None:
+        stored = self._states.get(check_task_id(task_id))
+        return None if stored is None else (stored[0], copy.deepcopy(stored[1]))
+
+    def save(self, task_id: str, state: dict[str, Any], *, expected: int, clear_journal: bool = False) -> int:
+        current = self._states.get(check_task_id(task_id), (0, {}))[0]
+        if current != expected:
+            raise ConflictError(f"task {task_id!r}: stored version {current}, expected {expected}")
+        self._states[task_id] = (current + 1, copy.deepcopy(state))
+        if clear_journal:
+            self._journals[task_id] = []
+        return current + 1
+
+    def journal_append(self, task_id: str, entries: Sequence[dict[str, Any]]) -> None:
+        self._journals.setdefault(check_task_id(task_id), []).extend(copy.deepcopy(list(entries)))
+
+    def journal_read(self, task_id: str) -> list[dict[str, Any]]:
+        return copy.deepcopy(self._journals.get(check_task_id(task_id), []))
+
+    def audit_append(self, task_id: str, entry: dict[str, Any]) -> None:
+        self._audits.setdefault(check_task_id(task_id), []).append(copy.deepcopy(entry))
+
+    def audit_read(self, task_id: str) -> list[dict[str, Any]]:
+        return copy.deepcopy(self._audits.get(check_task_id(task_id), []))
+
+    def put_document(self, task_id: str, name: str, document: dict[str, Any]) -> None:
+        self._documents.setdefault(check_task_id(task_id), {})[check_document_name(name)] = copy.deepcopy(document)
+
+    def get_document(self, task_id: str, name: str) -> dict[str, Any] | None:
+        found = self._documents.get(check_task_id(task_id), {}).get(check_document_name(name))
+        return None if found is None else copy.deepcopy(found)
+
+    def documents(self, task_id: str) -> list[str]:
+        return sorted(self._documents.get(check_task_id(task_id), {}))