aurochs-core 0.1.0__tar.gz

aurochs_core-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy / ruff
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# IDE
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

aurochs_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stefan Kovalik <stefan@aurochs.agency>
+
+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.

aurochs_core-0.1.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: aurochs-core
+Version: 0.1.0
+Summary: Shared infrastructure for the Aurochs agency line plugins.
+Project-URL: Homepage, https://github.com/skovalik/aurochs-core
+Project-URL: Repository, https://github.com/skovalik/aurochs-core
+Project-URL: Issues, https://github.com/skovalik/aurochs-core/issues
+Author-email: Stefan Kovalik <stefan@aurochs.agency>
+Maintainer-email: Stefan Kovalik <stefan@aurochs.agency>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: advisory-lock,aurochs,lockfile,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: psutil>=5.9
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: types-psutil; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# aurochs-core
+
+Shared infrastructure for the Aurochs agency line plugins. Not user-facing.
+
+Ships the canonical advisory-lockfile classes (`WriteLock`, `MigrateLock`, `LockError`)
+and the SQLite connection helper (`db_connect`) used by every plugin in the Aurochs
+agency line (`aurochs-recall`, `aurochs-voice`, `aurochs-llm-scrub`, `aurochs-seo-geo`).
+
+Plugins still own their own `MigrationRunner`, types, and schema modules — only the
+truly shared substrate lives here.
+
+## Public surface
+
+```python
+from aurochs_core import LockError, MigrateLock, WriteLock, db_connect
+```
+
+Pragma contract applied by `db_connect()`:
+
+- `foreign_keys = ON`
+- `journal_mode = WAL`
+- `synchronous = NORMAL`
+- `busy_timeout = 30000` (30s)
+- `row_factory = sqlite3.Row`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aurochs_core-0.1.0/README.md

@@ -0,0 +1,28 @@
+# aurochs-core
+
+Shared infrastructure for the Aurochs agency line plugins. Not user-facing.
+
+Ships the canonical advisory-lockfile classes (`WriteLock`, `MigrateLock`, `LockError`)
+and the SQLite connection helper (`db_connect`) used by every plugin in the Aurochs
+agency line (`aurochs-recall`, `aurochs-voice`, `aurochs-llm-scrub`, `aurochs-seo-geo`).
+
+Plugins still own their own `MigrationRunner`, types, and schema modules — only the
+truly shared substrate lives here.
+
+## Public surface
+
+```python
+from aurochs_core import LockError, MigrateLock, WriteLock, db_connect
+```
+
+Pragma contract applied by `db_connect()`:
+
+- `foreign_keys = ON`
+- `journal_mode = WAL`
+- `synchronous = NORMAL`
+- `busy_timeout = 30000` (30s)
+- `row_factory = sqlite3.Row`
+
+## License
+
+MIT — see [LICENSE](LICENSE).

aurochs_core-0.1.0/aurochs_core/__init__.py

@@ -0,0 +1,8 @@
+"""aurochs-core — shared infrastructure for the Aurochs agency line."""
+
+from aurochs_core.db import db_connect
+from aurochs_core.locks import LockError, MigrateLock, WriteLock
+
+__version__ = "0.1.0"
+
+__all__ = ["LockError", "MigrateLock", "WriteLock", "db_connect"]

aurochs_core-0.1.0/aurochs_core/db.py

@@ -0,0 +1,104 @@
+"""Shared SQLite connection helper.
+
+Establishes the canonical pragma contract used by every Aurochs plugin:
+``foreign_keys=ON``, ``journal_mode=WAL``, ``synchronous=NORMAL``,
+``busy_timeout=30000``, ``isolation_level=None`` (autocommit). Row
+factory is ``sqlite3.Row``.
+
+The pragmas applied here are not optional — leaving any of them off
+changes correctness, not just performance:
+
+* ``foreign_keys = ON`` — SQLite default is OFF. Without this, every
+  FK declared in the schema is documentation, not enforcement.
+* ``journal_mode = WAL`` — concurrent readers + one writer; required
+  for the OS-lockfile concurrency model.
+* ``busy_timeout = 30000`` — 30s cap before raising ``database is
+  locked``.
+* ``synchronous = NORMAL`` — WAL-safe; ``FULL`` is unnecessary with
+  WAL and costs roughly 2x on bulk inserts.
+* ``isolation_level=None`` — autocommit; the caller manages
+  transactions explicitly (BEGIN/COMMIT). Required for plugin
+  ``MigrationRunner`` paths that issue ``BEGIN EXCLUSIVE``.
+
+NOTE: Plugins still own their own ``MigrationRunner`` — schema
+migration logic varies per-plugin (different migration files,
+different ``schema_version`` table ownership). This module ships only
+the connection helper.
+
+Connections are NOT thread-safe by default. Multiprocessing workers
+MUST call ``db_connect()`` themselves rather than passing a connection
+across the process boundary — pickling a sqlite3 Connection is not
+supported.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+# Pragmas applied to every connection, in order. Read by tests to
+# assert the contract.
+_REQUIRED_PRAGMAS: tuple[tuple[str, str], ...] = (
+    ("foreign_keys", "ON"),
+    ("journal_mode", "WAL"),
+    ("synchronous", "NORMAL"),
+    ("busy_timeout", "30000"),
+)
+
+
+def db_connect(db_path: Path | str) -> sqlite3.Connection:
+    """Open a sqlite3 Connection with the canonical Aurochs pragma contract.
+
+    Creates the database file if it does not exist (and the parent dir
+    if needed). The caller owns the connection — close it (or use as a
+    context manager) when done.
+
+    Parameters
+    ----------
+    db_path:
+        Path to the database file. ``":memory:"`` is supported for
+        tests; pass it as a literal str.
+
+    Returns
+    -------
+    sqlite3.Connection
+        Autocommit connection with ``Row`` row_factory and all required
+        pragmas applied. ``isolation_level=None`` so the caller manages
+        transactions explicitly (BEGIN/COMMIT) — necessary for the
+        EXCLUSIVE migration transactions plugins use.
+
+    Raises
+    ------
+    RuntimeError
+        If ``foreign_keys = ON`` did not take (some sqlite builds ignore
+        the pragma inside a transaction; we fail loud rather than silently
+        running with FKs off).
+    """
+    if isinstance(db_path, str) and db_path == ":memory:":
+        target: str | Path = ":memory:"
+    else:
+        target = Path(db_path)
+        if isinstance(target, Path):
+            target.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(
+        str(target),
+        isolation_level=None,  # autocommit; we manage transactions manually
+        check_same_thread=True,
+    )
+    conn.row_factory = sqlite3.Row
+
+    for pragma, value in _REQUIRED_PRAGMAS:
+        conn.execute(f"PRAGMA {pragma} = {value}")
+
+    # Verify foreign_keys actually took. Some sqlite builds ignore the
+    # pragma inside a transaction; fail loud if it didn't.
+    enforced = conn.execute("PRAGMA foreign_keys").fetchone()[0]
+    if enforced != 1:
+        conn.close()
+        raise RuntimeError(
+            "PRAGMA foreign_keys = ON failed to apply. This sqlite build "
+            "may not support FK enforcement; refusing to continue."
+        )
+
+    return conn

aurochs_core-0.1.0/aurochs_core/locks.py

@@ -0,0 +1,334 @@
+"""OS-level advisory lockfiles.
+
+Single-writer enforcement at the OS level — not just SQLite-level. Two
+distinct lockfile classes serve different concurrency contracts:
+
+* ``WriteLock`` — held by ANY writer (indexer, extractor, taxonomy mutation).
+  Path: ``<db>.write.lock`` next to the database file.
+* ``MigrateLock`` — held during the entire migration sequence, including
+  the ``schema_version`` status update. Path: ``<db>.migrate.lock``.
+
+POSIX uses ``fcntl.flock``; Windows uses ``msvcrt.locking``. The Windows
+implementation hardens against fork-inheritance leaks (``close_fds=True``,
+non-inheritable handle) and ghost locks (stale-PID detection via
+``psutil.pid_exists``).
+
+Each lockfile records the holder PID. If a process tries to acquire and
+finds the lock held but the recorded PID no longer exists, the lock is
+considered stale and force-released with an audit-log entry. This closes
+the "user kill -9'd indexer; lock now blocks all subsequent runs" failure
+mode.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+from types import TracebackType
+
+
+class LockError(RuntimeError):
+    """Raised when a lock cannot be acquired (held by another process)."""
+
+    def __init__(self, lockfile: Path, holder_pid: int | None) -> None:
+        msg = f"Lock {lockfile} is held"
+        if holder_pid is not None:
+            msg += f" by PID {holder_pid}"
+        super().__init__(msg)
+        self.lockfile = lockfile
+        self.holder_pid = holder_pid
+
+
+def _pid_alive(pid: int) -> bool:
+    """Check whether a PID corresponds to a living process.
+
+    Tries ``psutil.pid_exists`` first (handles cross-platform edge cases
+    cleanly); falls back to ``os.kill(pid, 0)`` on POSIX and a Windows
+    ``OpenProcess`` probe via ctypes if psutil is unavailable.
+    """
+    try:
+        import psutil  # type: ignore[import-not-found, unused-ignore]
+
+        return bool(psutil.pid_exists(pid))
+    except ImportError:
+        pass
+
+    if sys.platform == "win32":
+        # Best-effort ctypes probe so the spine remains importable without
+        # psutil installed.
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+            kernel32 = ctypes.windll.kernel32  # type: ignore[attr-defined, unused-ignore]
+            kernel32.OpenProcess.argtypes = (
+                wintypes.DWORD,
+                wintypes.BOOL,
+                wintypes.DWORD,
+            )
+            kernel32.OpenProcess.restype = wintypes.HANDLE
+            handle = kernel32.OpenProcess(
+                PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+            )
+            if not handle:
+                return False
+            kernel32.CloseHandle(handle)
+            return True
+        except Exception:
+            # Conservative default: assume alive so we don't steal a
+            # legitimately held lock.
+            return True
+    try:
+        os.kill(pid, 0)
+        return True
+    except (ProcessLookupError, PermissionError):
+        # PermissionError means the PID exists but isn't ours — still alive.
+        return isinstance(sys.exc_info()[1], PermissionError)
+    except OSError:
+        return False
+
+
+class _LockfileBase:
+    """Shared behavior for advisory lockfiles.
+
+    Subclasses set ``suffix`` (e.g. ``".write.lock"``). The concrete
+    acquire/release implementation differs by platform.
+    """
+
+    suffix: str = ".lock"
+
+    def __init__(self, db_path: Path | str, *, timeout: float = 0.0) -> None:
+        """Construct a lock pointing at ``{db_path}{suffix}``.
+
+        ``timeout`` is the number of seconds to wait for the lock before
+        raising ``LockError``. ``0`` (default) = fail fast.
+        """
+        db = Path(db_path)
+        self.path: Path = db.with_name(db.name + self.suffix)
+        self.timeout: float = float(timeout)
+        self._fd: int | None = None
+        self._acquired: bool = False
+
+    # ----- subclass hooks -------------------------------------------------
+
+    def _try_lock(self, fd: int) -> bool:
+        """Attempt to lock ``fd`` non-blocking. Return True on success."""
+        raise NotImplementedError
+
+    def _unlock(self, fd: int) -> None:
+        """Release the OS-level lock on ``fd``."""
+        raise NotImplementedError
+
+    # ----- public API ----------------------------------------------------
+
+    def acquire(self) -> None:
+        """Acquire the lock, retrying up to ``timeout`` seconds.
+
+        On timeout, raises ``LockError``. If the holder PID recorded in the
+        lockfile is dead, the lock is force-released first (stale-PID
+        detection).
+        """
+        if self._acquired:
+            raise RuntimeError("Lock already acquired by this object")
+
+        deadline = time.monotonic() + self.timeout
+        while True:
+            fd = self._open_lockfile()
+            if self._try_lock(fd):
+                # Got it. Stamp our PID into the file and remember it.
+                self._fd = fd
+                self._write_pid(fd)
+                self._acquired = True
+                return
+
+            # Failed to lock — peek at the recorded PID to decide stale-vs-live.
+            holder_pid = self._read_pid_from_path()
+            os.close(fd)
+
+            if holder_pid is not None and not _pid_alive(holder_pid):
+                # Stale lock. Force-release and retry once. The retry path
+                # only runs once because we can't be unlucky-stale twice.
+                self._force_release_stale(holder_pid)
+                continue
+
+            if time.monotonic() >= deadline:
+                raise LockError(self.path, holder_pid)
+            time.sleep(0.1)
+
+    def release(self) -> None:
+        """Release the lock. Safe to call even if not acquired.
+
+        On POSIX the lockfile is unlinked after release. On Windows, msvcrt
+        keeps an exclusive byte-range lock that prevents unlink even after
+        the FD is closed in some sharing modes — so we leave the file in
+        place. The next acquire will reuse it. The PID stamping inside the
+        file means stale-lock detection still works across runs.
+        """
+        if self._fd is not None:
+            try:
+                self._unlock(self._fd)
+            finally:
+                try:
+                    os.close(self._fd)
+                except OSError:
+                    pass
+                self._fd = None
+        self._acquired = False
+        # Best-effort lockfile removal — only on POSIX. On Windows leaving
+        # the pid-file alone is the safer behavior.
+        if sys.platform != "win32":
+            try:
+                self.path.unlink(missing_ok=True)
+            except OSError:
+                pass
+
+    # ----- helpers -------------------------------------------------------
+
+    def _open_lockfile(self) -> int:
+        """Open the lockfile, creating it if needed, with non-inheritable FD."""
+        # O_CLOEXEC: don't leak the FD to child processes (subprocess /
+        # multiprocessing). On Windows there's no O_CLOEXEC but we set
+        # the inheritable flag explicitly below.
+        flags = os.O_RDWR | os.O_CREAT
+        if hasattr(os, "O_CLOEXEC"):
+            flags |= os.O_CLOEXEC
+
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(str(self.path), flags, 0o644)
+        # Belt-and-braces on Windows where O_CLOEXEC isn't available.
+        try:
+            os.set_inheritable(fd, False)
+        except (OSError, AttributeError):
+            pass
+        return fd
+
+    def _write_pid(self, fd: int) -> None:
+        """Stamp the current PID into the lockfile body."""
+        try:
+            os.lseek(fd, 0, os.SEEK_SET)
+            os.ftruncate(fd, 0)
+            os.write(fd, str(os.getpid()).encode("ascii"))
+            try:
+                os.fsync(fd)
+            except OSError:
+                pass
+        except OSError:
+            # PID-stamping is best-effort. If it fails the lock is still
+            # held; we just lose stale-detection on the next attempt.
+            pass
+
+    def _read_pid_from_path(self) -> int | None:
+        """Read the recorded PID from the lockfile body, if any."""
+        try:
+            raw = self.path.read_bytes().strip()
+        except OSError:
+            return None
+        if not raw:
+            return None
+        try:
+            return int(raw)
+        except ValueError:
+            return None
+
+    def _force_release_stale(self, dead_pid: int) -> None:
+        """Remove a stale lockfile whose holder PID is gone."""
+        # Best-effort. A concurrent acquirer might be racing us; if so the
+        # next acquire-attempt will simply fail and retry.
+        try:
+            self.path.unlink(missing_ok=True)
+        except OSError:
+            pass
+
+    # ----- context manager -----------------------------------------------
+
+    def __enter__(self) -> _LockfileBase:
+        self.acquire()
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.release()
+
+
+# ---------------------------------------------------------------------------
+# Platform-specific implementations
+# ---------------------------------------------------------------------------
+
+if sys.platform == "win32":
+    import msvcrt
+
+    class _WindowsLockMixin(_LockfileBase):
+        def _try_lock(self, fd: int) -> bool:
+            try:
+                # LK_NBLCK: non-blocking lock of the first byte. msvcrt
+                # locks ranges, not the whole file, but byte 0 is enough
+                # for advisory mutual exclusion.
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)  # type: ignore[attr-defined, unused-ignore]
+                return True
+            except OSError:
+                return False
+
+        def _unlock(self, fd: int) -> None:
+            try:
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)  # type: ignore[attr-defined, unused-ignore]
+            except OSError:
+                # Already released or process dying; no recourse.
+                pass
+
+    _PlatformLock = _WindowsLockMixin
+
+else:
+    import fcntl
+
+    class _PosixLockMixin(_LockfileBase):
+        def _try_lock(self, fd: int) -> bool:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                return True
+            except OSError:
+                return False
+
+        def _unlock(self, fd: int) -> None:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_UN)
+            except OSError:
+                pass
+
+    _PlatformLock = _PosixLockMixin  # type: ignore[misc, assignment]
+
+
+# ---------------------------------------------------------------------------
+# Public lock classes
+# ---------------------------------------------------------------------------
+
+
+class WriteLock(_PlatformLock):
+    """Single-writer advisory lock — held by any process that writes
+    plugin-owned state (drawers, extractions, taxonomy mutations).
+
+    Usage::
+
+        from aurochs_core import WriteLock
+
+        with WriteLock(db_path, timeout=30):
+            # do writes
+            ...
+    """
+
+    suffix = ".write.lock"
+
+
+class MigrateLock(_PlatformLock):
+    """Migration advisory lock — held across an entire migration sequence,
+    including the ``schema_version`` status update. Distinct from
+    ``WriteLock`` so writers and migrators can be diagnosed independently.
+    """
+
+    suffix = ".migrate.lock"

aurochs_core-0.1.0/pyproject.toml

@@ -0,0 +1,178 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aurochs-core"
+version = "0.1.0"
+description = "Shared infrastructure for the Aurochs agency line plugins."
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Stefan Kovalik", email = "stefan@aurochs.agency" },
+]
+maintainers = [
+    { name = "Stefan Kovalik", email = "stefan@aurochs.agency" },
+]
+keywords = [
+    "sqlite",
+    "lockfile",
+    "advisory-lock",
+    "aurochs",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "psutil>=5.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "types-psutil",
+]
+
+[project.urls]
+Homepage = "https://github.com/skovalik/aurochs-core"
+Repository = "https://github.com/skovalik/aurochs-core"
+Issues = "https://github.com/skovalik/aurochs-core/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["aurochs_core"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/aurochs_core",
+    "/tests",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]
+
+# ---- ruff -------------------------------------------------------------------
+
+[tool.ruff]
+target-version = "py313"
+line-length = 100
+extend-exclude = [
+    "build",
+    "dist",
+    ".venv",
+    "venv",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+]
+ignore = [
+    "E501",  # line length (handled by formatter)
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["N802", "N806", "N803"]
+# locks.py vendors a platform-shim with intentional try/except/pass blocks
+# (best-effort cleanup paths where contextlib.suppress would change perf
+# semantics) and a Windows constant in PEP 8-violating SHOUT_CASE form to
+# match the Win32 API name. This matches the vendored copies across the
+# Aurochs plugin line.
+"aurochs_core/locks.py" = ["N806", "SIM105"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "lf"
+
+# ---- mypy -------------------------------------------------------------------
+
+[tool.mypy]
+python_version = "3.13"
+strict = true
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+no_implicit_optional = true
+warn_return_any = true
+exclude = [
+    "build/",
+    "dist/",
+]
+
+[[tool.mypy.overrides]]
+module = [
+    "psutil.*",
+]
+ignore_missing_imports = true
+
+# ---- pytest -----------------------------------------------------------------
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+python_files = ["test_*.py", "*_test.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = [
+    "-ra",
+    "--strict-markers",
+    "--strict-config",
+    "--showlocals",
+    "--tb=short",
+]
+markers = [
+    "unit: unit tests, no I/O",
+    "integration: integration tests with sqlite",
+    "windows: windows-specific tests",
+    "macos: macos-specific tests",
+    "linux: linux-specific tests",
+]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning:pkg_resources.*",
+]
+
+# ---- coverage ---------------------------------------------------------------
+
+[tool.coverage.run]
+branch = true
+source = ["aurochs_core"]
+omit = [
+    "*/tests/*",
+]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+]
+show_missing = true
+skip_covered = false

aurochs_core-0.1.0/tests/test_db.py

@@ -0,0 +1,159 @@
+"""Unit tests for db_connect — pragma contract.
+
+The shared db_connect helper applies the canonical Aurochs pragma
+contract to every connection. These tests assert each pragma is set
+exactly as documented; deviation is a regression that affects every
+plugin downstream.
+"""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from aurochs_core import db_connect
+
+
+class TestPragmas:
+    def test_foreign_keys_pragma_on(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            result = conn.execute("PRAGMA foreign_keys").fetchone()[0]
+            assert result == 1, "PRAGMA foreign_keys must be ON every connection"
+        finally:
+            conn.close()
+
+    def test_journal_mode_wal(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            result = conn.execute("PRAGMA journal_mode").fetchone()[0]
+            assert result.lower() == "wal"
+        finally:
+            conn.close()
+
+    def test_synchronous_normal(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            # NORMAL = 1 in PRAGMA result.
+            result = conn.execute("PRAGMA synchronous").fetchone()[0]
+            assert result == 1
+        finally:
+            conn.close()
+
+    def test_busy_timeout_30s(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            result = conn.execute("PRAGMA busy_timeout").fetchone()[0]
+            assert result == 30000
+        finally:
+            conn.close()
+
+
+class TestRowFactory:
+    def test_row_factory_is_sqlite_row(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            assert conn.row_factory is sqlite3.Row
+        finally:
+            conn.close()
+
+    def test_rows_support_mapping_access(self, tmp_path: Path) -> None:
+        """Row factory should let us index columns by name."""
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            conn.execute("CREATE TABLE t (id INTEGER PRIMARY KEY, name TEXT)")
+            conn.execute("INSERT INTO t (name) VALUES (?)", ("alpha",))
+            conn.commit()
+            row = conn.execute("SELECT id, name FROM t").fetchone()
+            assert row["name"] == "alpha"
+            assert row["id"] == 1
+        finally:
+            conn.close()
+
+
+class TestFkEnforcement:
+    def test_fk_actually_enforces(self, tmp_path: Path) -> None:
+        """Smoke-test: with FKs ON, violating-row inserts raise IntegrityError."""
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            conn.execute(
+                "CREATE TABLE parent (id INTEGER PRIMARY KEY, name TEXT)"
+            )
+            conn.execute(
+                "CREATE TABLE child ("
+                "  id INTEGER PRIMARY KEY,"
+                "  parent_id INTEGER,"
+                "  FOREIGN KEY (parent_id) REFERENCES parent(id)"
+                ")"
+            )
+            conn.commit()
+            with pytest.raises(sqlite3.IntegrityError):
+                conn.execute(
+                    "INSERT INTO child (parent_id) VALUES (?)", (999,)
+                )
+        finally:
+            conn.close()
+
+
+class TestPathArg:
+    def test_path_object_accepted(self, tmp_path: Path) -> None:
+        """db_path: Path is the documented signature; pathlib.Path must work."""
+        db: Path = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            assert db.exists()
+        finally:
+            conn.close()
+
+    def test_creates_parent_dir(self, tmp_path: Path) -> None:
+        """Fresh install should create the db's parent directory if missing."""
+        nested = tmp_path / "nested" / "deeply" / "test.db"
+        conn = db_connect(nested)
+        try:
+            assert nested.parent.exists()
+            assert nested.exists()
+        finally:
+            conn.close()
+
+    def test_memory_db(self) -> None:
+        """``:memory:`` must be honored as an in-memory DB, not a file path."""
+        conn = db_connect(":memory:")
+        try:
+            result = conn.execute("PRAGMA foreign_keys").fetchone()[0]
+            assert result == 1
+        finally:
+            conn.close()
+
+
+class TestAutocommit:
+    def test_isolation_level_is_none(self, tmp_path: Path) -> None:
+        """Autocommit mode is required for plugin BEGIN EXCLUSIVE migrations."""
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            assert conn.isolation_level is None
+        finally:
+            conn.close()
+
+    def test_begin_exclusive_works(self, tmp_path: Path) -> None:
+        """Plugins issue BEGIN EXCLUSIVE manually; verify the path is open."""
+        db = tmp_path / "test.db"
+        conn = db_connect(db)
+        try:
+            conn.execute("CREATE TABLE t (id INTEGER PRIMARY KEY)")
+            conn.execute("BEGIN EXCLUSIVE")
+            conn.execute("INSERT INTO t (id) VALUES (?)", (1,))
+            conn.execute("COMMIT")
+            row = conn.execute("SELECT COUNT(*) FROM t").fetchone()
+            assert row[0] == 1
+        finally:
+            conn.close()

aurochs_core-0.1.0/tests/test_locks.py

@@ -0,0 +1,174 @@
+"""Unit tests for OS-level advisory lockfiles.
+
+Mocking-friendly: we don't fork a real second process to test mutual
+exclusion. Instead we test the file-level state machine — acquire,
+release, double-acquire raises, stale-PID detection.
+
+A second-process scenario (where one Python interpreter holds the lock
+and another tries to acquire) is covered by integration tests in the
+plugin repos that consume aurochs-core, not this unit test, because
+spawning processes is slow and brittle on Windows CI.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+from aurochs_core.locks import LockError, MigrateLock, WriteLock, _pid_alive
+
+# ---------------------------------------------------------------------------
+# Single-process state machine
+# ---------------------------------------------------------------------------
+
+
+class TestSingleProcess:
+    def test_acquire_release(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        lock = WriteLock(db)
+        lock.acquire()
+        try:
+            assert lock.path.exists()
+        finally:
+            lock.release()
+        # After release the PID stamp should be readable. On Windows,
+        # msvcrt.locking blocks reads from a SECOND handle while the lock
+        # is held — so we only verify the stamp post-release.
+        stamped = int(lock.path.read_text().strip() or "0")
+        assert stamped == os.getpid()
+
+    def test_context_manager(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        with WriteLock(db) as lock:
+            assert lock.path.exists()
+        # On POSIX the file is cleaned up; on Windows we deliberately leave
+        # it in place because msvcrt holds the byte-range even after close
+        # and we don't want race conditions on unlink. Either way, the OS
+        # lock has been released — re-acquire must succeed.
+        with WriteLock(db) as lock2:
+            assert lock2.path.exists()
+
+    def test_double_acquire_same_object_raises(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        lock = WriteLock(db)
+        lock.acquire()
+        try:
+            with pytest.raises(RuntimeError):
+                lock.acquire()
+        finally:
+            lock.release()
+
+    def test_release_without_acquire_safe(self, tmp_path: Path) -> None:
+        db = tmp_path / "test.db"
+        lock = WriteLock(db)
+        # Should be a no-op, not raise.
+        lock.release()
+
+    def test_write_and_migrate_locks_distinct(self, tmp_path: Path) -> None:
+        """A WriteLock and a MigrateLock can be held simultaneously by the
+        same process — they target different lockfiles."""
+        db = tmp_path / "test.db"
+        with WriteLock(db) as wl, MigrateLock(db) as ml:
+            assert wl.path != ml.path
+            assert wl.path.name.endswith(".write.lock")
+            assert ml.path.name.endswith(".migrate.lock")
+
+
+# ---------------------------------------------------------------------------
+# Stale-PID detection
+# ---------------------------------------------------------------------------
+
+
+class TestStalePidDetection:
+    def test_stale_lockfile_with_dead_pid_is_force_released(
+        self, tmp_path: Path
+    ) -> None:
+        """Pre-create a lockfile claiming a dead PID; acquire must succeed."""
+        db = tmp_path / "test.db"
+        lockfile = db.with_name(db.name + ".write.lock")
+        lockfile.parent.mkdir(parents=True, exist_ok=True)
+        # Use a PID we're confident is dead. PID 1 is normally init/launchd
+        # and will be alive — pick a high random PID instead. 999_999_999
+        # is well above the typical PID_MAX on Linux/macOS/Windows.
+        lockfile.write_text("999999999")
+
+        # The lockfile exists but no process actually holds the OS-level
+        # lock (we only wrote the PID, didn't fcntl/msvcrt-lock). The
+        # acquire path should succeed because it can take the OS-level
+        # lock — the stale-PID branch isn't strictly needed here, but the
+        # test confirms the happy path doesn't get confused by the file.
+        with WriteLock(db) as lock:
+            assert lock.path == lockfile
+
+    def test_pid_alive_self(self) -> None:
+        """Sanity: our own PID is reported alive."""
+        assert _pid_alive(os.getpid())
+
+    def test_pid_alive_dead_pid(self) -> None:
+        """A high-numbered PID that almost certainly doesn't exist must
+        be reported as dead (or, conservatively, as alive on platforms
+        where we can't tell — the code falls back to alive when ambiguous).
+
+        We accept either answer; the goal is to confirm the function
+        doesn't raise on an exotic input.
+        """
+        result = _pid_alive(999_999_999)
+        assert isinstance(result, bool)
+
+
+# ---------------------------------------------------------------------------
+# Concurrent acquire (in-process simulation via separate WriteLock objects)
+# ---------------------------------------------------------------------------
+
+
+class TestConcurrentInProcess:
+    def test_two_locks_same_file_one_wins(self, tmp_path: Path) -> None:
+        """Two WriteLock objects pointing at the same file: only one can
+        hold the OS-level lock at a time within a process.
+
+        On POSIX, fcntl.flock is per-file-descriptor but advisory between
+        processes — same-process double-locking via fcntl actually returns
+        success (POSIX-specific edge case). Windows msvcrt.locking is
+        strict. We accept either behavior here and just assert the API
+        doesn't crash.
+        """
+        db = tmp_path / "test.db"
+        lock_a = WriteLock(db, timeout=0)
+        lock_b = WriteLock(db, timeout=0)
+
+        lock_a.acquire()
+        try:
+            try:
+                lock_b.acquire()
+                # POSIX path — same-process flock is reentrant. Release.
+                lock_b.release()
+            except LockError:
+                # Windows path — strict mutual exclusion within process.
+                pass
+        finally:
+            lock_a.release()
+
+
+# ---------------------------------------------------------------------------
+# Public surface (re-exported from package root)
+# ---------------------------------------------------------------------------
+
+
+class TestPublicSurface:
+    def test_top_level_imports(self) -> None:
+        """The four documented public names import from package root."""
+        from aurochs_core import (
+            LockError as TopLockError,
+        )
+        from aurochs_core import (
+            MigrateLock as TopMigrateLock,
+        )
+        from aurochs_core import (
+            WriteLock as TopWriteLock,
+        )
+
+        assert TopLockError is LockError
+        assert TopMigrateLock is MigrateLock
+        assert TopWriteLock is WriteLock