brain-framework 9.0.1__py3-none-any.whl

bf/records.py

@@ -0,0 +1,277 @@
+"""Records live in monthly JSON Lines partitions: one line per source item, upserted by id."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from datetime import date
+from typing import Annotated, Literal
+
+from pydantic import Field, ValidationError
+
+from bf.models import MAX_PARTITION, NAME, Error, Model, Record, decode, encode, explain
+from bf.storage import Store, reader
+
+SNAPSHOT = "snapshot"
+UNDATED = "undated"
+_PENDING = "memories/.pending"
+_MANIFEST = _PENDING + "/manifest.json"
+_MANIFEST_LIMIT = 1 << 20
+
+
+class _Change(Model):
+    name: Annotated[str, Field(pattern=r"^(?:[0-9]{4}-[0-9]{2}|snapshot|undated)\.jsonl$")]
+    existed: bool
+
+
+class _Journal(Model):
+    version: Literal[1] = 1
+    source: Annotated[str, Field(pattern=NAME)]
+    complete: bool = False
+    changes: Annotated[list[_Change], Field(max_length=10_000)]
+
+
+def _pending(store: Store) -> bool:
+    try:
+        with store.parent(_MANIFEST):
+            return True
+    except FileNotFoundError:
+        return False
+
+
+def _clear(store: Store) -> None:
+    names = store.files(_PENDING)
+    if any(
+        not re.fullmatch(r"memories/\.pending/(?:manifest\.json|[0-9]+\.before|\.write-[0-9a-f]{32})", n) for n in names
+    ):
+        raise Error("unexpected file in memories/.pending; preserve it and repair the pending transaction")
+    # The completion marker remains until every staged file is gone.
+    for name in sorted(names, key=lambda name: name == _MANIFEST):
+        store.delete(name)
+    with suppress(FileNotFoundError):
+        store.rmdir(_PENDING)
+
+
+def recover(store: Store) -> None:
+    """Roll back an interrupted commit, under the caller's exclusive brain writer lock.
+
+    Originals and the manifest are durable evidence under memories/, never disposable state.
+    A completion marker means all partitions were committed (or restored) and only cleanup remains.
+    """
+    if not _pending(store):
+        return
+    try:
+        raw = store.read(_MANIFEST, _MANIFEST_LIMIT)
+    except FileNotFoundError:
+        # Preparation never changes a source before its manifest is durable.
+        _clear(store)
+        return
+    try:
+        journal = _Journal.model_validate(decode(raw))
+    except ValidationError as error:
+        raise Error("invalid memories/.pending manifest; preserve it and repair the pending transaction") from error
+    if len({change.name for change in journal.changes}) != len(journal.changes):
+        raise Error("duplicate paths in memories/.pending manifest")
+    if not journal.complete:
+        # Check all backups before restoring any source file.
+        for number, change in enumerate(journal.changes):
+            if change.existed:
+                store.read(f"{_PENDING}/{number}.before", MAX_PARTITION)
+        for number, change in enumerate(journal.changes):
+            target = f"memories/{journal.source}/{change.name}"
+            if change.existed:
+                store.write(target, store.read(f"{_PENDING}/{number}.before", MAX_PARTITION))
+            else:
+                with suppress(FileNotFoundError):
+                    store.delete(target)
+        journal.complete = True
+        store.write(_MANIFEST, encode(journal.model_dump()))
+    _clear(store)
+
+
+def require_ready(store: Store) -> None:
+    """Keep read operations from applying an untrusted on-disk recovery journal."""
+    if _pending(store):
+        raise Error("records contain an interrupted transaction; run bf build to recover it before reading")
+
+
+@contextmanager
+def reading(store: Store) -> Iterator[None]:
+    """Read a consistent set of partitions without changing durable evidence."""
+    with reader(store):
+        require_ready(store)
+        yield
+
+
+def _commit(store: Store, source: str, replacements: dict[str, bytes | None]) -> None:
+    if not replacements:
+        return
+    changes = []
+    for name in replacements:
+        try:
+            store.fingerprint(name)
+            existed = True
+        except FileNotFoundError:
+            existed = False
+        changes.append(_Change(name=name.removeprefix(f"memories/{source}/"), existed=existed))
+    journal = _Journal(source=source, changes=changes)
+    manifest = encode(journal.model_dump())
+    if len(manifest) > _MANIFEST_LIMIT:
+        raise Error("record transaction exceeds its manifest limit")
+    try:
+        for number, (name, change) in enumerate(zip(replacements, changes, strict=True)):
+            if change.existed:
+                store.write(f"{_PENDING}/{number}.before", store.read(name, MAX_PARTITION))
+        store.write(_MANIFEST, manifest)
+        for name, data in replacements.items():
+            if data is None:
+                store.delete(name)
+            else:
+                store.write(name, data)
+        journal.complete = True
+        store.write(_MANIFEST, encode(journal.model_dump()))
+    except BaseException as error:
+        try:
+            recover(store)
+        except (Error, OSError) as recovery_error:
+            raise Error("record transaction needs recovery; preserve memories/.pending and retry") from recovery_error
+        raise error
+    # A cleanup failure cannot turn a durable successful commit into a failed collection.
+    with suppress(OSError):
+        _clear(store)
+
+
+def partition(record: Record) -> str:
+    return record.time[:7] if record.time else UNDATED
+
+
+def path(source: str, name: str) -> str:
+    return f"memories/{source}/{name}.jsonl"
+
+
+def line(record: Record) -> bytes:
+    return encode(record.model_dump(exclude_defaults=True))
+
+
+def partitions(store: Store, source: str = "") -> list[str]:
+    """Record partitions of one source, or of every source; other files under memories/ are ignored."""
+    return [name for name in store.files(f"memories/{source}" if source else "memories") if name.endswith(".jsonl")]
+
+
+def parse(name: str, data: bytes) -> Iterator[Record]:
+    for number, raw in enumerate(data.splitlines(), 1):
+        if not raw.strip():
+            continue
+        try:
+            yield Record.model_validate(decode(raw))
+        except ValidationError as error:
+            raise Error(f"{name}:{number}: invalid record: {explain(error)}") from error
+        except Error as error:
+            raise Error(f"{name}:{number}: {error}") from error
+
+
+def load(store: Store, name: str) -> list[Record]:
+    source_of(name)
+    return list(parse(name, store.read(name, MAX_PARTITION)))
+
+
+def source_of(name: str) -> str:
+    parts = name.split("/")
+    if len(parts) != 3 or parts[0] != "memories" or not re.fullmatch(NAME, parts[1]):
+        raise Error(f"{name}: expected memories/<source>/<YYYY-MM|undated|snapshot>.jsonl")
+    filename = parts[2]
+    if filename not in {"undated.jsonl", "snapshot.jsonl"}:
+        try:
+            if not re.fullmatch(r"[0-9]{4}-[0-9]{2}\.jsonl", filename):
+                raise ValueError
+            date.fromisoformat(filename.removesuffix(".jsonl") + "-01")
+        except ValueError:
+            raise Error(f"{name}: expected a YYYY-MM, undated or snapshot JSON Lines partition") from None
+    return parts[1]
+
+
+def upsert(store: Store, source: str, incoming: list[Record], *, snapshot: bool) -> dict[str, int]:
+    """Window sources add or replace items by id; snapshot sources replace their complete catalog.
+
+    Each id appears once per source, in the partition of its event month, so a rescheduled
+    event moves between partitions instead of leaving a stale copy behind.
+    """
+    recover(store)
+    if not re.fullmatch(NAME, source):
+        raise Error("invalid record source")
+    if not incoming and not snapshot:
+        return {"added": 0, "updated": 0, "unchanged": 0, "removed": 0}
+    existing: dict[str, dict[str, Record]] = {}
+    located: dict[str, str] = {}
+    for name in partitions(store, source):
+        key = name.rsplit("/", 1)[1].removesuffix(".jsonl")
+        partition_records: dict[str, Record] = {}
+        for record in load(store, name):
+            if record.id in located:
+                raise Error(f"source {source} contains duplicate record ids; run bf validate and reconcile them")
+            located[record.id] = key
+            partition_records[record.id] = record
+        existing[key] = partition_records
+    before = {key: dict(records) for key, records in existing.items()}
+    counts = {"added": 0, "updated": 0, "unchanged": 0, "removed": 0}
+    if snapshot:
+        wanted = {r.id for r in incoming}
+        counts["removed"] = len(located.keys() - wanted)
+        existing = {SNAPSHOT: {}}
+    for record in incoming:
+        key = SNAPSHOT if snapshot else partition(record)
+        previous = before.get(located.get(record.id, ""), {}).get(record.id)
+        if previous and previous.updated and record.updated and previous.updated > record.updated:
+            # Historical backfills must not replace a known newer upstream revision.
+            record = previous
+            key = SNAPSHOT if snapshot else partition(record)
+        if previous is None:
+            counts["added"] += 1
+        elif previous.model_dump(exclude={"attributes": {"observed"}}) == record.model_dump(
+            exclude={"attributes": {"observed"}}
+        ):
+            counts["unchanged"] += 1
+            if previous.observed:
+                record = previous
+        else:
+            counts["updated"] += 1
+        if not snapshot and located.get(record.id, key) != key:
+            existing[located[record.id]].pop(record.id)
+        existing.setdefault(key, {})[record.id] = record
+    replacements: dict[str, bytes | None] = {}
+    for key in sorted(before.keys() | existing.keys()):
+        records = existing.get(key, {})
+        if records == before.get(key, {}):
+            continue
+        if records:
+            ordered = sorted(records.values(), key=lambda r: (r.time, r.id))
+            data = b"".join(line(r) for r in ordered)
+            if len(data) > MAX_PARTITION:
+                raise Error(f"{path(source, key)}: record partition exceeds its {MAX_PARTITION}-byte limit")
+            replacements[path(source, key)] = data
+        else:
+            replacements[path(source, key)] = None
+    _commit(store, source, replacements)
+    return counts
+
+
+def find(store: Store, source: str, record_id: str) -> tuple[str, Record] | None:
+    """Scan one source directly: exact record reads never depend on the derived index."""
+    if not re.fullmatch(NAME, source):
+        return None
+    unreadable = False
+    with reading(store):
+        for name in sorted(partitions(store, source), reverse=True):
+            try:
+                items = load(store, name)
+            except Error, OSError, UnicodeError:
+                # Match indexing's file boundary: one malformed partition must not hide other evidence.
+                unreadable = True
+                continue
+            for record in items:
+                if record.id == record_id:
+                    return name, record
+    if unreadable:
+        raise Error(f"source {source} has unreadable partitions; run bf validate before concluding a record is absent")
+    return None

bf/retrieve.py

@@ -0,0 +1,173 @@
+"""Search across brains and read exact notes, sections and records."""
+
+from __future__ import annotations
+
+import sqlite3
+from contextlib import suppress
+
+from bf import index, records, usage
+from bf.config import load
+from bf.health import source_health
+from bf.markdown import authored, section, split_ref
+from bf.models import MAX_REPLY, NOTICE, Error, Query, encode
+from bf.storage import Store, relative
+
+
+def bounded(value: dict[str, object], limit: int = MAX_REPLY) -> dict[str, object]:
+    if len(encode(value)) > limit:
+        raise Error("response exceeds its byte limit; narrow the request")
+    return value
+
+
+def search(stores: list[Store], query: Query, *, counted: bool = True) -> dict[str, object]:
+    """Merge per-brain results: relevance keeps each brain's order, a time window interleaves by time."""
+    results: list[list[dict[str, object]]] = []
+    stale = []
+    brains = []
+    problems: list[dict[str, object]] = []
+    last_error: Exception | None = None
+    owners: set[tuple[str, str]] = set()
+    identity = index.identity(query.text)
+    for store in stores:
+        name = store.root.name
+        try:
+            config = load(store)
+            name = config.name
+            with index.database(store) as (connection, state):
+                items = index.search(
+                    connection, query, active_sources={n for n, sensor in config.sensors.items() if sensor.enabled}
+                )
+                skipped = index.problems(connection)
+                if identity:
+                    owners.update((name, ref) for ref in index.identity_owners(connection, query.text))
+        except (Error, OSError, UnicodeError, sqlite3.DatabaseError) as error:
+            if len(stores) == 1:
+                raise
+            last_error = error
+            message = str(error) if isinstance(error, Error) else "inaccessible brain or cache; run bf status"
+            problems.append({"brain": name, "error": message.replace(str(store.root), "<brain>")})
+            continue
+        if skipped:
+            problems.append({"brain": name, "files": skipped})
+        brains.append((store, name))
+        if state != "ready":
+            stale.append(name)
+        if counted:
+            usage.note(store, "search", len(items))
+        results.append([{"brain": name, **item} for item in items])
+    if not results:
+        raise Error("no selected brain could be searched; run bf status with --brain for each brain") from last_error
+    if identity or query.recent or not query.text.strip():
+        merged = sorted(
+            (i for r in results for i in r), key=lambda i: (str(i.get("time", "")), str(i["ref"])), reverse=True
+        )
+        if identity:
+            # Keep canonical refs, alias owners and related evidence in that order, then newest first.
+            merged.sort(
+                key=lambda item: (
+                    str(item["ref"]) != query.text.strip(),
+                    (str(item["brain"]), str(item["ref"])) not in owners,
+                )
+            )
+    else:
+        # Interleave by rank: bm25 scores from different corpora are not comparable.
+        merged = [i for rank in range(query.limit) for r in results if rank < len(r) for i in [r[rank]]]
+    selected = merged[: query.limit]
+    reply: dict[str, object] = {"items": selected, "notice": NOTICE}
+    coverage = []
+    for store, name in brains:
+        names = {str(item["source"]) for item in selected if item["brain"] == name and "source" in item}
+        if query.source:
+            names.add(query.source)
+        if names:
+            try:
+                coverage.extend(
+                    {"brain": name, "source": source, **health}
+                    for source, health in source_health(store, names).items()
+                    if source in names
+                )
+            except Error, OSError, UnicodeError:
+                problems.append({"brain": name, "error": "collection coverage is unavailable; run bf status"})
+    if coverage:
+        reply["sources"] = coverage
+    if stale:
+        reply["stale"] = stale
+    if problems:
+        reply["problems"] = problems
+    return bounded(reply)
+
+
+def _brain(stores: list[Store], name: str) -> list[Store]:
+    if not name:
+        return stores
+    chosen = [store for store in stores if load(store).name == name]
+    if not chosen:
+        raise Error(f"unknown brain {name}; pass one of the searched brains")
+    return chosen
+
+
+def read(stores: list[Store], ref: str, brain: str = "") -> dict[str, object]:
+    """Resolve a note path, note section, `source:id` record or explicit identity in exactly one brain."""
+    if not ref or len(ref) > 8192:
+        raise Error("expected a reference of at most 8192 characters")
+    found = [(store, value) for store in _brain(stores, brain) if (value := _read(store, ref)) is not None]
+    if not found:
+        raise Error("reference not found; use bf search to locate it")
+    if len(found) > 1:
+        raise Error("reference exists in several brains; pass --brain NAME")
+    reply = bounded({**found[0][1], "notice": NOTICE})
+    usage.note(found[0][0], "read", 1)
+    return reply
+
+
+def _read(store: Store, ref: str) -> dict[str, object] | None:
+    name = load(store).name
+    path, fragment = split_ref(ref)
+    if authored(path):
+        relative(path)
+        try:
+            data = store.read(path, 4 << 20)
+        except FileNotFoundError:
+            return None
+        text = section(path, data, fragment) if fragment else data.decode("utf-8")
+        return {"brain": name, "ref": ref, "text": text}
+    located, aliases, cache_error = None, [], None
+    try:
+        with index.database(store) as (connection, _state):
+            located = connection.execute("SELECT path FROM items WHERE ref=?", (ref,)).fetchone()
+            aliases = connection.execute(
+                "SELECT i.ref FROM names n JOIN items i ON i.id=n.item WHERE n.name=? ORDER BY i.ref LIMIT 2",
+                (ref,),
+            ).fetchall()
+    except (Error, OSError, sqlite3.DatabaseError) as error:
+        # An exact source:id still has a file recovery path when its disposable cache is unavailable.
+        cache_error = error
+    source, separator, record_id = ref.partition(":")
+    if separator:
+        # The cache only locates the partition; the answer always comes from the record file itself.
+        found = None
+        if located:
+            hint = str(located["path"])
+            parts: tuple[str, ...] = ()
+            with suppress(Error):
+                parts = relative(hint)
+            if len(parts) == 3 and parts[:2] == ("memories", source) and parts[2].endswith(".jsonl"):
+                # Journal checks run before suppression; only an unusable cache hint is ignored.
+                with records.reading(store), suppress(Error, OSError, UnicodeError):
+                    hinted = next((r for r in records.load(store, hint) if r.id == record_id), None)
+                    if hinted:
+                        found = hint, hinted
+        found = found or records.find(store, source, record_id)
+        if found:
+            return {
+                "brain": name,
+                "ref": ref,
+                "path": found[0],
+                "record": found[1].model_dump(exclude_defaults=True),
+                "collection": source_health(store, [source])[source],
+            }
+    if cache_error:
+        raise Error("the search cache is unavailable; run bf build to resolve identities") from cache_error
+    if len(aliases) > 1:
+        raise Error("ambiguous identity; use bf search and read an exact ref")
+    return _read(store, aliases[0]["ref"]) if aliases and aliases[0]["ref"] != ref else None

bf/storage.py

@@ -0,0 +1,223 @@
+"""Confined, bounded filesystem access and one physical-brain writer lock."""
+
+from __future__ import annotations
+
+import fcntl
+import os
+import stat
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager, suppress
+from pathlib import Path, PurePosixPath
+
+from bf.models import MAX_FILE, MAX_FILES, Error, digest
+
+
+class BusyError(Error):
+    """Another process holds the brain writer lock."""
+
+
+_DIR = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
+
+
+def relative(value: str) -> tuple[str, ...]:
+    path = PurePosixPath(value)
+    parts = value.split("/")
+    if path.is_absolute() or any(p in {"", ".", ".."} for p in parts) or "\x00" in value or "\\" in value:
+        raise Error("expected a normalized brain-relative path")
+    return tuple(parts)
+
+
+class Store:
+    """All descendants are opened through no-follow directory descriptors."""
+
+    def __init__(self, root: Path) -> None:
+        try:
+            self.root = root.resolve(strict=True)
+        except OSError as error:
+            raise Error("brain directory does not exist; pass an existing --brain or BF_BRAIN") from error
+        if not self.root.is_dir():
+            raise Error("brain must be a directory")
+
+    @contextmanager
+    def parent(self, name: str, *, create: bool = False) -> Iterator[tuple[int, str]]:
+        parts = relative(name)
+        descriptor = os.open(self.root, _DIR)
+        try:
+            for part in parts[:-1]:
+                if create:
+                    try:
+                        os.mkdir(part, 0o700, dir_fd=descriptor)
+                    except FileExistsError:
+                        pass
+                    else:
+                        # Persist the new directory entry before a transaction can depend on its files.
+                        os.fsync(descriptor)
+                child = os.open(part, _DIR, dir_fd=descriptor)
+                os.close(descriptor)
+                descriptor = child
+            yield descriptor, parts[-1]
+        finally:
+            os.close(descriptor)
+
+    def read(self, name: str, limit: int = MAX_FILE) -> bytes:
+        with self.parent(name) as (parent, leaf):
+            fd = os.open(leaf, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC, dir_fd=parent)
+            with os.fdopen(fd, "rb") as stream:
+                if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                    raise Error(f"{name}: expected a regular file")
+                data = stream.read(limit + 1)
+        if len(data) > limit:
+            raise Error(f"{name}: file exceeds {limit} bytes")
+        return data
+
+    def write(self, name: str, data: bytes) -> None:
+        """Replace a regular file atomically; readers see the old or the new bytes, never a mix."""
+        with self.parent(name, create=True) as (parent, leaf):
+            temporary = ".write-" + os.urandom(16).hex()
+            fd = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=parent)
+            try:
+                with os.fdopen(fd, "wb") as stream:
+                    stream.write(data)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+                try:
+                    info = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+                except FileNotFoundError:
+                    pass
+                else:
+                    if not stat.S_ISREG(info.st_mode):
+                        raise Error(f"{name}: refusing to replace a non-regular file")
+                os.replace(temporary, leaf, src_dir_fd=parent, dst_dir_fd=parent)
+                os.fsync(parent)
+            finally:
+                with suppress(FileNotFoundError):
+                    os.unlink(temporary, dir_fd=parent)
+
+    def delete(self, name: str) -> None:
+        with self.parent(name) as (parent, leaf):
+            if not stat.S_ISREG(os.stat(leaf, dir_fd=parent, follow_symlinks=False).st_mode):
+                raise Error(f"{name}: refusing to delete a non-regular file")
+            os.unlink(leaf, dir_fd=parent)
+            os.fsync(parent)
+
+    def rmdir(self, name: str) -> None:
+        """Remove an empty directory without following links."""
+        with self.parent(name) as (parent, leaf):
+            if not stat.S_ISDIR(os.stat(leaf, dir_fd=parent, follow_symlinks=False).st_mode):
+                raise Error(f"{name}: expected a directory")
+            os.rmdir(leaf, dir_fd=parent)
+            os.fsync(parent)
+
+    def files(self, directory: str) -> list[str]:
+        """Bound the entire traversal, including directories and ignored extensions."""
+        relative(directory)
+        result: list[str] = []
+        visited = 0
+
+        def visit(fd: int, prefix: str) -> None:
+            nonlocal visited
+            if prefix.count("/") > 64:
+                raise Error("directory exceeds the 64-level depth limit")
+            with os.scandir(fd) as entries:
+                for entry in entries:
+                    visited += 1
+                    if visited > MAX_FILES:
+                        raise Error(f"{directory} exceeds the {MAX_FILES:,}-entry scan limit")
+                    path = f"{prefix}/{entry.name}"
+                    info = entry.stat(follow_symlinks=False)
+                    if stat.S_ISDIR(info.st_mode):
+                        child = os.open(entry.name, _DIR, dir_fd=fd)
+                        try:
+                            visit(child, path)
+                        finally:
+                            os.close(child)
+                    elif stat.S_ISREG(info.st_mode):
+                        result.append(path)
+                    else:
+                        raise Error(f"{path}: symlinks and special files are forbidden")
+
+        try:
+            with self.parent(directory) as (parent, leaf):
+                fd = os.open(leaf, _DIR, dir_fd=parent)
+        except FileNotFoundError:
+            return []
+        try:
+            visit(fd, directory)
+        finally:
+            os.close(fd)
+        return sorted(result)
+
+    def fingerprint(self, name: str) -> tuple[int, int, int, int]:
+        """Size, mtime, ctime and inode: ctime catches an edit whose mtime was preserved."""
+        with self.parent(name) as (parent, leaf):
+            info = os.stat(leaf, dir_fd=parent, follow_symlinks=False)
+            if not stat.S_ISREG(info.st_mode):
+                raise Error(f"{name}: expected a regular file")
+            return info.st_size, info.st_mtime_ns, info.st_ctime_ns, info.st_ino
+
+
+def state_store(root: Path) -> Store:
+    """Private runtime state stays outside the evidence brain."""
+    home = Path(os.environ.get("XDG_STATE_HOME", str(Path.home() / ".local/state"))).expanduser()
+    if not home.is_absolute() or home.resolve().is_relative_to(root):
+        raise Error("state directory must be absolute and outside the brain")
+    directory = home / "bf" / digest(os.fsencode(root))
+    # Reject redirected state roots before creating any descendant.
+    for path in [directory, *directory.parents]:
+        if path.is_symlink():
+            raise Error("state directory may not contain symlinks")
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if directory.stat().st_uid != os.getuid() or directory.stat().st_mode & 0o077:
+        raise Error("state directory must be owned by you with mode 700")
+    return Store(directory)
+
+
+@contextmanager
+def _lock(store: Store, name: str, wait: float, *, shared: bool = False) -> Iterator[None]:
+    state = state_store(store.root)
+    with state.parent(name) as (parent, leaf):
+        flags = os.O_RDWR | os.O_NOFOLLOW | os.O_NONBLOCK
+        try:
+            fd = os.open(leaf, flags | os.O_CREAT, 0o600, dir_fd=parent)
+        except FileNotFoundError:
+            # Concurrent first creation can report ENOENT on macOS. Reopen only an existing lock;
+            # keep the pinned parent and safety flags, and never replace a missing lock on recovery.
+            fd = os.open(leaf, flags, dir_fd=parent)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            raise Error("invalid writer lock")
+        deadline = time.monotonic() + wait
+        while True:
+            try:
+                fcntl.flock(fd, (fcntl.LOCK_SH if shared else fcntl.LOCK_EX) | fcntl.LOCK_NB)
+                break
+            except BlockingIOError as error:
+                if time.monotonic() >= deadline:
+                    raise BusyError("another writer is active for this brain; retry after it finishes") from error
+                time.sleep(0.05)
+        yield
+    finally:
+        os.close(fd)
+
+
+@contextmanager
+def writer(store: Store, wait: float = 0) -> Iterator[None]:
+    """Serialize writers of one physical brain; wait up to `wait` seconds for another writer."""
+    with _lock(store, "write.lock", wait):
+        yield
+
+
+@contextmanager
+def reader(store: Store, wait: float = 120) -> Iterator[None]:
+    """Keep record partitions stable during one exact read; readers can run concurrently."""
+    with _lock(store, "write.lock", wait, shared=True):
+        yield
+
+
+@contextmanager
+def collecting(store: Store, sensor: str, wait: float = 0) -> Iterator[None]:
+    """Order runs of one sensor without blocking offline reads while its provider is running."""
+    relative(sensor)
+    with _lock(store, f"collect-{sensor}.lock", wait):
+        yield