pyuncommonkit 0.1.0__py3-none-any.whl

commonkit/__init__.py

@@ -0,0 +1,19 @@
+"""Named shared-memory segments for numpy arrays.
+
+The name is for Fortran's ``COMMON`` block: a named region several separately
+compiled programs agree to share. The name is the whole interface, and the
+segment outlives whoever wrote it.
+
+``store`` is the mechanism and carries the measured reasons behind it, ``keys``
+the addressing, ``cache`` the in-process memo that keeps a tight loop from
+paying an attach per call.
+"""
+from .cache import TieredPixelCache
+from .keys import KeyScheme, parse, register, relpath, scheme_for
+from .shared import shared_store
+from .store import KeyCollision, SharedArrayStore
+
+__all__ = [
+    "KeyCollision", "KeyScheme", "SharedArrayStore", "TieredPixelCache",
+    "parse", "register", "relpath", "scheme_for", "shared_store",
+]

commonkit/cache.py

@@ -0,0 +1,125 @@
+"""Two-tier pixel cache: an in-process memo over the shared store.
+
+Why two tiers and not a straight replacement, in one measurement:
+
+The consumer's face-crop path calls its pixel accessor **twice per face**
+-- once for the base dimensions, once for the crop. An 18-face page is
+therefore 36 lookups. Today that is one 38 ms decode plus 35 free in-process
+hits. Against a shared store alone it would be 36 attaches at ~3.3 ms each =
+119 ms, **three times slower than doing nothing at all**. Attaching is cheap, but
+it is not free, and a loop that attaches per crop is the one access pattern that
+turns a cache into a pessimization.
+
+So L1 memoises the ATTACHED MAPPING, not a second copy of the pixels. The first
+lookup attaches; every later lookup in that process is a dict hit. The pixels
+still live once in shared memory and are still shared across processes -- L1 adds
+no bytes, it removes syscalls.
+
+Tier order: L1 in-process memo -> L2 shared store -> decode.
+"""
+from __future__ import annotations
+
+from collections import Counter
+
+import numpy as np
+
+from .store import KeyCollision
+
+
+class TieredPixelCache:
+    """Satisfies the consumer's ``PixelCache`` protocol.
+
+    ``l1`` is anything with ``get``/``set_array`` (the original consumer
+    passes an LRU array cache); ``l2`` is a
+    :class:`~commonkit.store.SharedArrayStore`. Either may be None,
+    which degrades to the other -- and with both None this is a no-op cache,
+    leaving its caller exactly as it would be with no cache at all.
+    """
+
+    def __init__(self, l1=None, l2=None):
+        self.l1 = l1
+        self.l2 = l2
+        self.stats: Counter = Counter()
+
+    # ``_base_array`` checks for this and prefers it over the bytes path.
+    def get(self, key: str):
+        """The PixelCache protocol: the array, or None."""
+        return self.get_with_source(key)[0]
+
+    def get_with_source(self, key: str):
+        """``(array, source)`` -- which TIER answered, or ``(None, "decode")``.
+
+        The return channel this class used to lack, and the lack of which was a
+        real defect rather than an inelegance. ``entry.decoded`` could not ask
+        what happened, so it inferred it from counter DELTAS -- reading
+        ``shm_hit`` off this object, which deliberately does not tick it because
+        the store already does. The inference silently defaulted to "decode",
+        so every cross-process attach was reported as a decode.
+
+        Answering directly deletes the inference instead of correcting it. It is
+        also the only thread-safe shape: this cache is a module-global shared
+        across a node's CONCURRENCY threads, so recording "what I did last" on
+        ``self`` would be a race between them.
+        """
+        if self.l1 is not None:
+            arr = self.l1.get(key)
+            if arr is not None:
+                self.stats["l1_hit"] += 1
+                return arr, "l1"
+        if self.l2 is not None:
+            arr = self.l2.attach(key)
+            if arr is not None:
+                # The store counts the hit (and the publish, below) itself.
+                # Counting it here too doubled both in drain_stats, which
+                # sums the tier's counters with the store's.
+                # Promote so a crop loop pays one attach, not one per crop.
+                if self.l1 is not None:
+                    try:
+                        self.l1.set_array(key, arr)
+                    except Exception:  # noqa: BLE001, S110 -- an L1 that can't take the array costs a later attach, never an error
+                        pass
+                return arr, "shm"
+        self.stats["miss"] += 1
+        return None, "decode"
+
+    def set_array(self, key: str, arr) -> None:
+        """Called by ``_base_array`` after a decode. Raises only :class:`KeyCollision`."""
+        if self.l1 is not None:
+            try:
+                self.l1.set_array(key, arr)
+            except Exception:  # noqa: BLE001, S110 -- an L1 that can't take the array costs a later decode, never an error
+                pass
+        if self.l2 is not None:
+            try:
+                if not self.l2.publish(key, arr):
+                    self.stats["shm_declined"] += 1
+            except KeyCollision:
+                # The one exception that must reach the caller (contract §6.4): a
+                # broken key scheme hidden here would serve two contents under one key.
+                raise
+            except Exception:                                  # noqa: BLE001
+                self.stats["shm_publish_failed"] += 1
+
+    def set(self, key: str, value: bytes) -> None:
+        """Bytes path, for protocol compliance. ``_base_array`` prefers
+        ``set_array`` and will not normally reach this."""
+        try:
+            import io
+            arr = np.load(io.BytesIO(value), allow_pickle=False)
+        except Exception:  # noqa: BLE001 -- undecodable bytes are a miss: the cache never raises
+            return
+        self.set_array(key, arr)    # outside the try, so a KeyCollision gets out
+
+    def drain_stats(self) -> Counter:
+        """Take and reset counters, including the store's own."""
+        out = Counter(self.stats)
+        self.stats.clear()
+        if self.l2 is not None:
+            try:
+                out.update(self.l2.drain_stats())
+            except Exception:  # noqa: BLE001, S110 -- a store whose stats fail still lets the tier's own counters out
+                pass
+        return out
+
+    def __repr__(self) -> str:
+        return f"<TieredPixelCache l1={self.l1!r} l2={self.l2!r}>"

commonkit/keys.py

@@ -0,0 +1,229 @@
+"""Addressing: the key for a segment, and the path that key names.
+
+Key shape::
+
+    {domain}:{version}:{form}:{digest}:{variant}
+
+Path shape::
+
+    {root}/{form}/{digest[:2]}/{digest}.{variant}.npy
+
+Two-level sharding like a CAS, so no directory ever holds a million entries.
+
+A :class:`KeyScheme` fixes one domain's vocabulary. The pieces mean:
+
+``domain``
+    Who the segments belong to -- ``pixels``, ``audio``. Also the dispatch key:
+    schemes register themselves, so :func:`parse` and :func:`relpath` can work
+    from a key alone and one store can hold several domains.
+``version``
+    The DECODE CONTRACT, not a release number. Bump it when what a segment
+    contains changes meaning, so old segments become unreachable rather than
+    being attached by a reader that assumes the new contract. (``pixels`` is at
+    ``v3`` because ``v2`` segments could hold LA/RGBA, which ``v3`` readers
+    assume away.)
+``form``
+    What KIND of array -- ``pil`` uint8 images, ``f32chw`` model tensors,
+    ``wav16k`` int16 audio. Deliberately NOT colour order: a BGR view is
+    converted from the one stored RGB segment in about a millisecond against a
+    38 ms decode, and storing both would double the tree to save that
+    millisecond while letting the two drift.
+``variant``
+    What distinguishes two renderings of the SAME source bytes. This is the
+    axis that differs per domain and the reason the scheme is a class rather
+    than a constant: images vary by orientation (``o0`` raw, ``o1`` oriented,
+    ``oa`` Apple), a waveform would vary by sample rate (``sr16000``).
+
+The form segment precedes the digest so that a domain whose variant suffix is
+already load-bearing elsewhere keeps it at the end of the key, untouched.
+"""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+#: Segments are addressed by md5, lowercase. Every pattern here is used with
+#: ``fullmatch``, never ``match`` with ``$``: ``$`` also matches before a final
+#: newline, which let ``"...\n"`` through as a digest or token (contract §3.1).
+_DIGEST_RE = re.compile(r"[0-9a-f]{32}")
+
+#: Every other component is a bare lowercase token. Restrictive on purpose:
+#: these become PATH components, and a key is the only thing standing between
+#: a caller and a path the reaper will later be asked to unlink.
+_TOKEN_RE = re.compile(r"[a-z0-9]+")
+
+#: Fold ASCII upper case only (contract §3.3): ``str.lower`` folds far more.
+_ASCII_LOWER = str.maketrans("ABCDEFGHIJKLMNOPQRSTUVWXYZ", "abcdefghijklmnopqrstuvwxyz")
+
+
+class KeyScheme:
+    """One domain's key vocabulary, and the only thing that builds its keys.
+
+    ``variants`` is either an explicit tuple of legal variants or a regex
+    string for an open-ended axis (sample rates, say). Explicit is preferred
+    where the set is closed: an unknown variant is then a loud error at the
+    call site rather than a segment nobody will ever look for.
+    """
+
+    def __init__(self, domain: str, version: str, forms: Iterable[str],
+                 variants, dtypes: dict[str, str] | None = None):
+        for name, value in (("domain", domain), ("version", version)):
+            if not _TOKEN_RE.fullmatch(str(value)):
+                raise ValueError(f"{name} must be [a-z0-9]+, got {value!r}")
+        self.domain = str(domain)
+        self.version = str(version)
+        self.forms = tuple(forms)
+        if not self.forms:
+            raise ValueError(f"{self.domain}: at least one form is required")
+        for form in self.forms:
+            if not _TOKEN_RE.fullmatch(form):
+                raise ValueError(f"form must be [a-z0-9]+, got {form!r}")
+        if len(set(self.forms)) != len(self.forms):
+            raise ValueError(f"{self.domain}: forms must be distinct, got {self.forms}")
+
+        if isinstance(variants, str):
+            self.variants: tuple[str, ...] = ()
+            self._variant_re = re.compile(variants)
+            #: The pattern's text, which is what makes two pattern schemes the
+            #: same or different (contract §3.4).
+            self.variant_pattern: str | None = variants
+        else:
+            self.variants = tuple(variants)
+            if not self.variants:
+                raise ValueError(f"{self.domain}: at least one variant")
+            for variant in self.variants:
+                if not _TOKEN_RE.fullmatch(variant):
+                    raise ValueError(f"variant must be [a-z0-9]+, got {variant!r}")
+            self._variant_re = None
+            self.variant_pattern = None
+
+        # form -> required numpy dtype NAME, for forms whose consumers rely on
+        # one. Declared here rather than branched on inside the store, which
+        # would put one domain's policy in the generic layer. A segment that
+        # violates it is refused at publish: a bad segment is not one bad call,
+        # it is published once and then poisons every reader that attaches it,
+        # on a path where a miss is meant to be the worst outcome available.
+        self.dtypes = dict(dtypes or {})
+        for form in self.dtypes:
+            if form not in self.forms:
+                raise ValueError(f"{self.domain}: dtype for unknown form {form!r}")
+
+        self._key_re = re.compile(
+            rf"{re.escape(self.domain)}:{re.escape(self.version)}:"
+            r"(?P<form>[a-z0-9]+):(?P<digest>[0-9a-f]{32}):"
+            r"(?P<variant>[a-z0-9]+)")
+
+    # ------------------------------------------------------------- building
+
+    @property
+    def default_form(self) -> str:
+        return self.forms[0]
+
+    def dtype_for(self, form: str) -> str | None:
+        """The dtype ``form`` must have, or None when anything goes."""
+        return self.dtypes.get(form)
+
+    def valid_variant(self, variant: str) -> bool:
+        """A token, and in the closed set or matched WHOLE by the pattern (contract §3.2).
+
+        ``re.match`` anchored only the start, so ``sr[0-9]+`` accepted ``sr16000x``;
+        and a pattern like ``sr.+`` could accept ``sr-1``, which no parser reads back.
+        """
+        variant = str(variant)
+        if not _TOKEN_RE.fullmatch(variant):
+            return False
+        if self._variant_re is not None:
+            return self._variant_re.fullmatch(variant) is not None
+        return variant in self.variants
+
+    def key(self, digest: str, variant: str, form: str | None = None) -> str:
+        """The store key for one array. Raises on anything it cannot address."""
+        digest = str(digest).translate(_ASCII_LOWER)
+        if not _DIGEST_RE.fullmatch(digest):
+            raise ValueError(f"not an md5 digest: {digest!r}")
+        form = self.default_form if form is None else str(form)
+        if form not in self.forms:
+            raise ValueError(
+                f"{self.domain}: unknown form {form!r}; have {self.forms}")
+        variant = str(variant)
+        if not self.valid_variant(variant):
+            raise ValueError(f"{self.domain}: unknown variant {variant!r}")
+        return f"{self.domain}:{self.version}:{form}:{digest}:{variant}"
+
+    # -------------------------------------------------------------- reading
+
+    def parse(self, key: str) -> tuple[str, str, str]:
+        """``key -> (form, digest, variant)``. Raises on anything unparseable.
+
+        Strict on purpose: this is the only thing between a malformed key and
+        a path the reaper might later unlink.
+        """
+        m = self._key_re.fullmatch(str(key))
+        if m is None:
+            raise ValueError(f"unparseable {self.domain} key: {key!r}")
+        form, variant = m.group("form"), m.group("variant")
+        if form not in self.forms or not self.valid_variant(variant):
+            raise ValueError(f"unparseable {self.domain} key: {key!r}")
+        return form, m.group("digest"), variant
+
+    def relpath(self, key: str) -> str:
+        """``key -> "{form}/{2-hex}/{digest}.{variant}.npy"``, never absolute."""
+        form, digest, variant = self.parse(key)
+        return f"{form}/{digest[:2]}/{digest}.{variant}.npy"
+
+    def __repr__(self) -> str:
+        return f"<KeyScheme {self.domain}:{self.version} forms={self.forms}>"
+
+
+# ------------------------------------------------------------------ registry
+#
+# Dispatch by domain is what lets ONE store hold several domains: the store
+# parses a key without being told which scheme it belongs to, so it never has
+# to grow a parameter for something the key already says.
+
+_REGISTRY: dict[str, KeyScheme] = {}
+
+
+def register(scheme: KeyScheme) -> KeyScheme:
+    """Register ``scheme``, refusing a second, different one for its domain.
+
+    Idempotent for an identical re-registration, because a module that binds a
+    scheme at import time may legitimately be imported twice under different
+    names. A DISAGREEING second registration is the bug worth catching: two
+    spellings of one domain means the publisher writes one key and the reader
+    asks for another, and the hit rate silently goes to zero with no error.
+    """
+    prior = _REGISTRY.get(scheme.domain)
+    if prior is not None:
+        same = (prior.version == scheme.version
+                and prior.forms == scheme.forms
+                # A closed variant SET (contract §3.4): order carries no meaning there,
+                # unlike forms, whose first is the default.
+                and set(prior.variants) == set(scheme.variants)
+                and prior.variant_pattern == scheme.variant_pattern
+                and prior.dtypes == scheme.dtypes)
+        if not same:
+            raise ValueError(
+                f"two disagreeing schemes for domain {scheme.domain!r}")
+        return prior
+    _REGISTRY[scheme.domain] = scheme
+    return scheme
+
+
+def scheme_for(key: str) -> KeyScheme:
+    """The registered scheme that owns ``key``."""
+    domain = str(key).split(":", 1)[0]
+    scheme = _REGISTRY.get(domain)
+    if scheme is None:
+        raise ValueError(f"no registered scheme for key: {key!r}")
+    return scheme
+
+
+def parse(key: str) -> tuple[str, str, str]:
+    """``key -> (form, digest, variant)``, dispatching on the key's domain."""
+    return scheme_for(key).parse(key)
+
+
+def relpath(key: str) -> str:
+    """``key -> relative segment path``, dispatching on the key's domain."""
+    return scheme_for(key).relpath(key)

commonkit/read.py

@@ -0,0 +1,49 @@
+"""Counting what a lookup did, in ONE vocabulary.
+
+A store answers three ways and the names for them are worth owning centrally,
+because the alternative is what happened before this module existed: two paths
+to the same pixels each decided independently what to call a hit, wrote the
+SAME counter names for DIFFERENT events, and nothing downstream could tell
+which one it was reading. One of them classified by counter DELTA and was
+wrong for two days; a correct production measurement was retracted on the
+strength of the ambiguity.
+
+The counter PREFIX is the caller's, not ours: ``pixels_shm`` and ``audio_shm``
+are different measurements and must not collide in one stats table.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+#: Every tier a lookup can be answered by. ``decode`` means "nothing had it" --
+#: the caller recomputes, which is always allowed and never an error.
+SOURCES = ("l1", "shm", "decode")
+
+
+def note(stats: Any, source: str, *, prefix: str) -> str:
+    """Tick ``{prefix}{source}``. THE one place that counter is written.
+
+    Returns ``source`` so callers can use this inline. A bad source name is a
+    programming error and raises: these counters are the instrument the whole
+    exercise is judged by, and a typo would silently invent a tier.
+    """
+    if source not in SOURCES:
+        raise ValueError(f"unknown source {source!r}; have {SOURCES}")
+    if stats is not None:
+        stats[f"{prefix}{source}"] += 1
+    return source
+
+
+def attach(store: Any, key: str) -> Any | None:
+    """The array for ``key``, or None. A miss is never an error.
+
+    An absent store, an unusable key, an absent segment and a torn file all
+    return None, because every caller's answer to all four is the same:
+    recompute it.
+    """
+    if store is None or not key:
+        return None
+    try:
+        return store.attach(key)
+    except Exception:                                          # noqa: BLE001
+        return None

commonkit/shared.py

@@ -0,0 +1,227 @@
+"""The ONE store per host that every commonkit user shares, and its tree-wide policy.
+
+Why one store rather than one per application, measured on an M4 Max (macOS, 16 KB pages)
+by the first consumer:
+
+* Every budget is enforced per TREE, by whichever process happens to reap. Two
+  applications with two roots therefore hold the SUM of their budgets, and neither
+  sees the other's usage. One root means one budget and one age-out for everything.
+* On macOS, Time Machine's hourly local snapshots keep a reaped segment's blocks
+  allocated (a 539 MB segment reaped after a snapshot freed 0 MB, TM exclusion of
+  ~/Library/Caches notwithstanding). A tree that turns over within the hour can pin up
+  to ~24x its budget of purgeable space until the snapshots thin. That is why the macOS
+  budget is 2 GB, and why a second tree with its own budget multiplies the pinned space.
+
+Tree-wide policy -- root, byte budget, TTL, free-space floor, reap interval, largest
+array, fsync, republish verification -- comes ONLY from the tree's ``.policy.json``, the
+environment (``COMMONKIT_STORE_*``) or the defaults here, never from a caller, because the
+reaper applies whatever the reaping process was given to every segment in the tree: a
+caller with a longer TTL or a bigger budget would silently override everyone else's. A
+caller chooses only what concerns itself: ``mode``, how it reads (``attach``: ``mmap``
+shares one physical copy, ``read`` gives it a private one), and the smallest array worth
+storing. Tests may pass a ``root`` to stay out of the shared tree.
+
+The policy FILE wins over the environment (C7), because the environment is per process
+and the tree is not: on thresher the policy lived in ``~/.bashrc``, so an app launched
+from the Finder ran with the defaults and reaped a 7 GB tree down to 2 GB. A file at the
+root is seen by every process that finds the root. The environment fills only what the
+file leaves out (contract §10.6).
+
+Segments of different domains coexist because forms partition the tree
+(``{form}/{digest[:2]}/...``). Form names are therefore global: pick ones no other
+domain uses.
+"""
+from __future__ import annotations
+
+import json
+import math
+import os
+import re
+import stat
+import sys
+
+from .store import SharedArrayStore
+
+ENV_PREFIX = "COMMONKIT_STORE_"
+_DARWIN = sys.platform == "darwin"
+
+#: Per-platform defaults. macOS: the user cache directory on the internal SSD -- it has no
+#: /dev/shm, the SSD beat a RAM disk on first attach (0.69 ms against 0.76 ms), and a
+#: ``ram://`` disk commits its whole size up front as dirty memory. Linux: /dev/shm, which
+#: is RAM, so the budget is its only real bound.
+DEFAULTS = {
+    "ROOT": (os.path.expanduser("~/Library/Caches/commonkit/store") if _DARWIN
+             else "/dev/shm/commonkit"),
+    "MAX_GB": 2.0 if _DARWIN else 8.0,
+    "MIN_FREE_GB": 8.0,
+    "TTL_S": 900.0,
+    "REAP_S": 30.0,
+    "MAX_ARRAY_BYTES": 128 * 2**20,
+    "FSYNC": False,
+    "VERIFY_REPUBLISH": False,
+}
+
+#: The tree's policy file, directly under the root (contract §10.5), and the most of it
+#: that is read: a real one is a few hundred bytes.
+POLICY_FILE = ".policy.json"
+_POLICY_MAX_BYTES = 65536
+
+#: The settings that become byte counts, and their scale. The derived integer must fit
+#: in 64 signed bits (contract §10.2), or a value is malformed: ``int(float("inf"))``
+#: raised OverflowError out of ``shared_store`` until 2026-10-28.
+_BYTE_SCALE = {"MAX_GB": 2**30, "MIN_FREE_GB": 2**30, "MAX_ARRAY_BYTES": 1}
+
+#: The number grammar (contract §10.2). ``float()`` is far looser: ``inf``, ``nan``,
+#: ``1_000``, Arabic-Indic digits and Unicode whitespace all parse, and a Rust or C
+#: reader of the same environment would disagree with every one of them.
+_NUMBER_RE = re.compile(r"[+-]?([0-9]+(\.[0-9]*)?|\.[0-9]+)([eE][+-]?[0-9]+)?")
+_ASCII_SPACE = " \t\n\v\f\r"
+_FLAG_ON = frozenset({"1", "true", "yes", "on"})
+
+
+def parse_number(raw: str) -> float | None:
+    """A finite float from ``raw`` under the contract's grammar, or None if malformed."""
+    text = raw.strip(_ASCII_SPACE)
+    if not _NUMBER_RE.fullmatch(text):
+        return None
+    value = float(text)                 # the grammar is a subset of float()'s
+    return value if math.isfinite(value) else None
+
+
+def parse_flag(raw: str) -> bool:
+    """Whether ``raw`` turns a flag on (contract §10.3): exact, ASCII case-insensitive.
+
+    ``isascii`` first, because ``str.lower`` folds beyond ASCII. Nothing is trimmed:
+    ``" 1"`` is off, so a value means one thing whichever language reads it.
+    """
+    return raw.isascii() and raw.lower() in _FLAG_ON
+
+
+class _Object(dict):
+    """A JSON object that remembers whether its text repeated a key."""
+
+    duplicate = False
+
+
+def _object_pairs(pairs):
+    obj = _Object(pairs)
+    obj.duplicate = len(obj) != len(pairs)
+    return obj
+
+
+def _not_json(name):
+    raise ValueError(f"{name} is not JSON")
+
+
+def read_policy(root) -> dict:
+    """The tree's ``.policy.json`` as a dict, or ``{}`` when it is absent or invalid.
+
+    Invalid is ENTIRELY absent (contract §10.5): not a regular file, over 64 KiB,
+    not UTF-8, not JSON (``NaN`` and ``Infinity`` included), not an object, or a
+    repeated top-level key, which JSON parsers resolve differently. Never raises.
+    """
+    path = os.path.join(os.path.abspath(str(root)), POLICY_FILE)
+    try:
+        # stat first: opening a FIFO someone named .policy.json would block forever.
+        st = os.stat(path)
+        if not stat.S_ISREG(st.st_mode) or st.st_size > _POLICY_MAX_BYTES:
+            return {}
+        with open(path, "rb") as fh:
+            data = fh.read(_POLICY_MAX_BYTES + 1)
+        if len(data) > _POLICY_MAX_BYTES:
+            return {}
+        # Decoded first: json.loads on bytes would also accept UTF-16 and UTF-32.
+        doc = json.loads(data.decode("utf-8"), object_pairs_hook=_object_pairs,
+                         parse_constant=_not_json)
+    except Exception:                                          # noqa: BLE001
+        return {}
+    if not isinstance(doc, _Object) or doc.duplicate:
+        return {}
+    return dict(doc)
+
+
+def _from_policy(name: str, value):
+    """``value`` from the policy file as a setting of ``name``'s kind, or None (left out)."""
+    if isinstance(DEFAULTS[name], bool):
+        if isinstance(value, bool):
+            return value
+        return parse_flag(value) if isinstance(value, str) else None
+    if isinstance(value, bool):         # bool is an int to Python, never a number here
+        return None
+    if isinstance(value, (int, float)):
+        try:
+            value = float(value)        # an integer past the double range overflows
+        except OverflowError:
+            return None
+        return value if math.isfinite(value) else None
+    return parse_number(value) if isinstance(value, str) else None
+
+
+def _from_env(name: str):
+    raw = os.environ.get(ENV_PREFIX + name)
+    if raw is None or raw == "":
+        return None
+    if isinstance(DEFAULTS[name], bool):
+        return parse_flag(raw)
+    return parse_number(raw)
+
+
+def _in_range(name: str, value) -> bool:
+    scale = _BYTE_SCALE.get(name)
+    if scale is None:
+        return True
+    try:
+        n = int(value * scale)          # trunc; inf (1e300 GiB) raises OverflowError
+    except (OverflowError, ValueError):
+        return False
+    return -2**63 <= n <= 2**63 - 1
+
+
+def setting(name: str, policy: dict | None = None):
+    """The effective tree-wide value of ``name`` (a key of DEFAULTS).
+
+    The first valid one of: ``policy`` (a :func:`read_policy` result), the environment,
+    the default (contract §10.6). ``ROOT`` never comes from the policy file, which is
+    found BY the root. A malformed value is skipped rather than raised: like the store
+    itself, configuration must never be the reason a caller fails.
+    """
+    default = DEFAULTS[name]
+    if name == "ROOT":
+        raw = os.environ.get(ENV_PREFIX + name)
+        return os.path.expanduser(raw) if raw else default
+    candidates = []
+    if policy and name in policy:
+        candidates.append(_from_policy(name, policy[name]))
+    candidates.append(_from_env(name))
+    for value in candidates:
+        if value is not None and _in_range(name, value):
+            return type(default)(value)
+    return default
+
+
+def shared_store(*, mode: str = "readwrite", attach: str = "mmap",
+                 min_array_bytes: int = 256 * 1024, root=None) -> SharedArrayStore:
+    """The host's shared store, with the tree-wide policy from ``.policy.json`` and the
+    environment. The file is read once, here.
+
+    Never raises (the store's own contract): an unusable root comes up disabled.
+    """
+    root = root or setting("ROOT")
+    policy = read_policy(root)
+
+    def get(name):
+        return setting(name, policy)
+
+    return SharedArrayStore(
+        root,
+        mode=mode,
+        attach=attach,
+        max_bytes=int(get("MAX_GB") * 2**30),
+        min_free_bytes=int(get("MIN_FREE_GB") * 2**30),
+        ttl_s=get("TTL_S"),
+        min_array_bytes=min_array_bytes,
+        max_array_bytes=get("MAX_ARRAY_BYTES"),
+        reap_interval_s=get("REAP_S"),
+        fsync=get("FSYNC"),
+        verify_republish=get("VERIFY_REPUBLISH"),
+    )