dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/overlap_eval.py

@@ -0,0 +1,214 @@
+"""The overlap-evaluation harness — score a disjointness scorer against ground truth.
+
+An `overlap_policy.OverlapPolicy` is a *hook*; this module is the *instrument* that
+makes the hook produce a number — the admission twin of `dos.judge_eval`, and the
+direct realization of `docs/90 §2`'s "backtest study against a labeled corpus of
+concurrent runs, scored on detonations *missed* vs safe concurrency *forgone*."
+
+The friendliness thesis (`docs/113 §4`/§7): a seam is only research-grade if it ships
+the instrument that scores a contribution to it. Bring your own overlap scorer (an
+import-graph analyzer, a semantic-similarity model, a learned conflict predictor),
+bring a labelled corpus of concurrent-pair outcomes, and get back the two numbers that
+matter:
+
+  * **false-admit rate** — of the pairs the scorer ADMITTED, the fraction that actually
+    `collided`. THE DANGEROUS CELL (the admission analogue of the judge's false-clear):
+    a non-empty cell means the scorer admitted a pair that corrupted shared state. The
+    exit code of `dos overlap-eval` is this verdict, so CI fails on any leak.
+  * **safe-concurrency-forgone rate** — of the pairs that did NOT collide, the fraction
+    the scorer REFUSED. The cost a stricter scorer pays; the SAFE-direction failure (a
+    needless serialization, never a corruption), so it is a quality knob, not a gate.
+
+Ground truth is whether running the two trees concurrently ACTUALLY collided — a merge
+conflict, a detonation log — derived from artifacts, NEVER from a scorer (the same
+honesty stance as `judge_eval`: the eval is only as honest as its labels).
+
+Everything here is **pure**: it consumes already-built cases, runs the scorer **under
+the deterministic floor** (`admissible_under_floor`, so the eval measures exactly what
+the arbiter would admit — not the raw policy, which could "admit" a pair the floor then
+refuses), and counts. No I/O inside the scoring, no host names — it sits in the kernel
+layer beside `overlap_policy`. A policy that does I/O inside `overlaps` (a model) does
+it during scoring; that is the policy's surface, not the harness's.
+
+Why score under the floor, not the raw policy
+==============================================
+
+`score` runs each pair through `admissible_under_floor(policy, …)`, the SAME path
+`DisjointnessPredicate` uses — so the grid reflects the *arbiter's* verdict, which is
+the only verdict that matters operationally. A consequence worth stating: against the
+prefix floor, a policy CANNOT register a false-admit on a prefix-colliding pair (the
+floor refuses it regardless), so the false-admit cell is informative exactly where a
+policy's admit set could legitimately extend past the prefix rule — i.e. under a
+*stricter* floor (`docs/113 §3.1`, the glob-intersection floor). On today's prefix
+floor the cell measures whether a *looser* `ratio_max` admitted a real collision the
+soft-overlap tolerance should have caught. Either way it is the operationally-honest
+number: what the arbiter would have let through.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from dos.lane_overlap import OverlapDecision
+from dos.overlap_policy import OverlapPolicy, admissible_under_floor
+
+
+# A labelled example: the two trees + whether running them concurrently ACTUALLY
+# collided (ground truth from artifacts — a merge conflict, a detonation). The
+# trees are the same `list[str]` glob shape the arbiter leases.
+@dataclass(frozen=True)
+class OverlapCase:
+    tree_a: list[str]      # the requested tree
+    tree_b: list[str]      # the live-lease tree
+    collided: bool         # ground truth: did concurrent execution corrupt shared state?
+    label: str = ""        # optional human handle for the pair (carried, never scored)
+
+
+@dataclass(frozen=True)
+class OverlapReport:
+    """A scorer evaluated over labelled cases — the 2×2 confusion grid + rates.
+
+    The grid is the scorer's ADMIT/REFUSE verdict (under the floor) against each
+    pair's ground-truth collided/safe. The named cells:
+      * ``correct_admit`` — ADMIT a pair that did NOT collide  (right: safe concurrency
+                            allowed)
+      * ``false_admit``   — ADMIT a pair that DID collide      (THE DANGEROUS CELL: a
+                            collision let through — the one error admission must minimize)
+      * ``correct_refuse``— REFUSE a pair that DID collide      (right: a collision caught)
+      * ``safe_forgone``  — REFUSE a pair that did NOT collide   (wrong but SAFE: a
+                            needless serialization, never a corruption)
+    """
+
+    n: int
+    correct_admit: int
+    false_admit: int
+    correct_refuse: int
+    safe_forgone: int
+
+    # --- aggregates ---
+
+    @property
+    def n_admit(self) -> int:
+        return self.correct_admit + self.false_admit
+
+    @property
+    def n_refuse(self) -> int:
+        return self.correct_refuse + self.safe_forgone
+
+    @property
+    def n_collided(self) -> int:
+        """Ground-truth COLLIDING pairs — the denominator for the leak rate."""
+        return self.false_admit + self.correct_refuse
+
+    @property
+    def n_safe(self) -> int:
+        """Ground-truth SAFE (non-colliding) pairs — the denominator for forgone-rate."""
+        return self.correct_admit + self.safe_forgone
+
+    # --- derived rates (all guard against divide-by-zero by returning 0.0) ---
+
+    @property
+    def false_admit_rate(self) -> float:
+        """Of the pairs the scorer ADMITTED, the fraction that actually collided. The
+        precision-of-admission number: when this scorer says "safe to run together,"
+        how often is it wrong? THE single most important admission metric — a scorer is
+        only safe to trust on its own if this is zero. (Against the prefix floor this is
+        zero for prefix-colliding pairs by construction; it becomes informative under a
+        looser `ratio_max` or a stricter floor — see the module docstring.)"""
+        return (self.false_admit / self.n_admit) if self.n_admit else 0.0
+
+    @property
+    def collision_leak_rate(self) -> float:
+        """Of all ground-truth COLLIDING pairs, the fraction the scorer admitted. The
+        recall-of-collisions number from the other side: what share of real collisions
+        leaked past admission entirely. `docs/90 §2`'s "detonations missed"."""
+        return (self.false_admit / self.n_collided) if self.n_collided else 0.0
+
+    @property
+    def safe_forgone_rate(self) -> float:
+        """Of all ground-truth SAFE pairs, the fraction the scorer REFUSED. `docs/90
+        §2`'s "safe concurrency forgone" — the cost of a stricter scorer. SAFE-direction,
+        so this trades against throughput, never against integrity (a high value means
+        lost parallelism, never a corruption)."""
+        return (self.safe_forgone / self.n_safe) if self.n_safe else 0.0
+
+    @property
+    def admit_rate(self) -> float:
+        """Fraction of all pairs admitted. The seductive raw throughput number — to be
+        read ALONGSIDE the collision cost it bought (`docs/90 §2`'s economic floor: the
+        right scalar is verified-velocity-per-$, never admit-rate alone)."""
+        return (self.n_admit / self.n) if self.n else 0.0
+
+    @property
+    def decisive_accuracy(self) -> float:
+        """How often the scorer's verdict matched ground truth — (correct_admit +
+        correct_refuse) / n. The overall correctness, both directions counted."""
+        return ((self.correct_admit + self.correct_refuse) / self.n) if self.n else 0.0
+
+    @property
+    def leaked(self) -> bool:
+        """True iff the dangerous cell is non-empty — the scorer admitted at least one
+        real collision. The boolean the `dos overlap-eval` exit code is built on."""
+        return self.false_admit > 0
+
+    def to_dict(self) -> dict:
+        return {
+            "n": self.n,
+            "grid": {
+                "correct_admit": self.correct_admit,
+                "false_admit": self.false_admit,
+                "correct_refuse": self.correct_refuse,
+                "safe_forgone": self.safe_forgone,
+            },
+            "rates": {
+                "false_admit_rate": round(self.false_admit_rate, 4),
+                "collision_leak_rate": round(self.collision_leak_rate, 4),
+                "safe_forgone_rate": round(self.safe_forgone_rate, 4),
+                "admit_rate": round(self.admit_rate, 4),
+                "decisive_accuracy": round(self.decisive_accuracy, 4),
+            },
+            "leaked": self.leaked,
+        }
+
+
+def _admits(policy: OverlapPolicy, case: OverlapCase, config: object) -> bool:
+    """Whether the ARBITER would admit this pair under ``policy`` — i.e. the policy
+    AND-ed under the deterministic prefix floor (`admissible_under_floor`), the exact
+    path `DisjointnessPredicate` takes. An empty tree on either side is the
+    unknown-blast-radius case the predicate (not the policy) owns; the eval models the
+    both-known scoring the policy actually governs, so a case with an empty tree is
+    scored by the floor alone (empty-vs-known → the floor's own handling)."""
+    decision: OverlapDecision = admissible_under_floor(
+        policy, list(case.tree_a), list(case.tree_b), config)
+    return decision.admissible
+
+
+def score(
+    policy: OverlapPolicy, cases: Iterable[OverlapCase], config: object = None,
+) -> OverlapReport:
+    """Run ``policy`` over labelled ``cases`` (UNDER THE FLOOR) and tabulate the grid.
+
+    Uses `admissible_under_floor`, so a policy that raises or returns garbage on a case
+    degrades to the floor verdict for that case rather than crashing the eval — the
+    report stays honest about a flaky scorer instead of hiding it (the `judge_eval`
+    fail-to-abstain posture, here fail-closed-to-floor). Pure: it reads the cases and
+    counts."""
+    ca = fa = cr = sf = 0
+    n = 0
+    for case in cases:
+        n += 1
+        admitted = _admits(policy, case, config)
+        if admitted:
+            if case.collided:
+                fa += 1   # false admit — the dangerous cell
+            else:
+                ca += 1   # correct admit
+        else:
+            if case.collided:
+                cr += 1   # correct refuse
+            else:
+                sf += 1   # safe concurrency forgone
+    return OverlapReport(
+        n=n, correct_admit=ca, false_admit=fa, correct_refuse=cr, safe_forgone=sf,
+    )

dos/overlap_policy.py

@@ -0,0 +1,342 @@
+"""The overlap-policy seam — Axis 7 of hackability: a pluggable disjointness scorer.
+
+Why this exists
+===============
+
+The arbiter's single most load-bearing verdict is *may these two known trees run
+concurrently?* — the thing that stops two agents writing the same region. Until
+this seam, that verdict was a **hardcoded `1/3` prefix-ratio** (`lane_overlap.
+overlap_verdict`) buried inside `admission.DisjointnessPredicate`. Every other
+hackability axis (reasons, renderers, predicates, judges, …) is *open* — bring
+your own implementation via data / an entry-point / a driver, never fork the
+package — but the disjointness *scorer* was sealed. `docs/90 §1`/`§2` named this
+exact scalar a deliberate research stand-in and specified the answer-shape; this
+module is that answer (the full argument is `docs/113`).
+
+The unit a policy rules on is two **known** trees (the unknown-blast-radius
+empty-tree asymmetry stays in `DisjointnessPredicate` — it is a soundness
+invariant, not a *scoring* choice, so a policy never sees it). A policy returns
+the existing typed `lane_overlap.OverlapDecision`, so it is a true drop-in at the
+one seam every collision check already routes through.
+
+The soundness floor — structural, not trusted
+==============================================
+
+This is the security-load-bearing core. A policy returns a verdict that *includes
+admit*, so — unlike an `AdmissionPredicate`, which can only refuse — the type
+alone no longer guarantees the safe direction. The guarantee is restored
+**structurally** by a deterministic floor:
+
+  > A resolved `OverlapPolicy` may turn an ADMIT into a REFUSE. It may never turn
+  > a REFUSE into an ADMIT relative to the unforgeable prefix floor.
+
+`admissible_under_floor` computes the deterministic prefix-disjointness floor
+(`PrefixOverlapPolicy` — pure path algebra, no provider, no I/O) AND the resolved
+policy's verdict, and admits only when **both** admit:
+
+    admit  ⟺  floor.admissible  AND  policy.admissible
+
+So a policy that admits a pair the prefix floor refuses is **structurally
+unable** to produce an admit (the floor is ANDed in, and the floor is not the
+plugin's to compute). The worst a buggy/hostile policy can do is *refuse* pairs
+the floor would admit — a visible, safe-direction loss of concurrency, never a
+collision. A policy that raises / returns the wrong type degrades to the floor
+verdict alone (fail-closed toward the prefix rule — i.e. to *today's* behavior).
+
+This is the admission analogue of the judge seam's fail-to-ABSTAIN and the
+predicate seam's conjunctive-only, and the `docs/76` design law applied to
+admission: a researcher changes *what counts as overlap* (the signal), never
+*which way the verdict fails* (the adjudication).
+
+Purity & layering
+=================
+
+Pure stdlib + the kernel leaves it delegates to (`lane_overlap`) — a Protocol,
+a built-in prefix policy, a resolver, and the floor-AND helper. No host names, no
+I/O inside a verdict. So it sits in the kernel layer beside `admission` (which
+likewise holds a pure protocol + resolver while real *implementations* live
+outside). A policy MAY do I/O *inside* `overlaps` (call a model, read an import
+graph) iff it lives in a driver — the JUDGE-rung allowance — but the kernel's own
+`PrefixOverlapPolicy` does not. Entry-point discovery (the one bit of I/O) happens
+at the call boundary in `active_overlap_policy`, exactly as `active_judges` /
+`active_predicates` / renderer discovery do.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Protocol, runtime_checkable
+
+from dos.lane_overlap import OVERLAP_RATIO_MAX, OverlapDecision, overlap_verdict
+
+
+@runtime_checkable
+class OverlapPolicy(Protocol):
+    """The contract a researcher implements to swap the disjointness *scorer*.
+
+    ``name`` is the token `dos overlap-eval --policy <name>` selects and
+    `dos doctor` lists. ``overlaps`` is handed two **known** (non-empty) trees +
+    the active ``config`` (read-only — it reads policy, e.g. a declared
+    ``ratio_max``, but the type gives it nothing to mutate) and returns an
+    `OverlapDecision` (the existing `lane_overlap` type).
+
+    A policy MAY do I/O *inside* ``overlaps`` (call a model, shell out, read an
+    import graph) — unlike a predicate or a renderer, which are pure — IFF it
+    lives in a driver, the same reason a ruling judge does. The discipline that
+    keeps it honest is NOT purity; it is the deterministic floor
+    (`admissible_under_floor`): whatever a policy returns, admission is the AND of
+    its admit and the kernel's own unforgeable prefix admit, so a policy is
+    structurally unable to admit a pair the prefix floor refuses.
+    """
+
+    name: str
+
+    def overlaps(
+        self, requested_tree: list[str], lease_tree: list[str], config: object,
+    ) -> OverlapDecision:
+        ...
+
+
+class PrefixOverlapPolicy:
+    """The built-in, always-available policy: today's `1/3` prefix-ratio scorer.
+
+    A verbatim wrap of `lane_overlap.overlap_verdict`, threading the workspace's
+    declared ``ratio_max`` (``config.overlap_ratio_max`` — `dos.toml [overlap]`,
+    defaulting to ⅓). With no `[overlap]` table and no plugin, the resolver
+    returns THIS policy and behavior is **byte-for-byte identical to before the
+    seam** — the load-bearing litmus (the entire existing arbiter/overlap suite
+    stays green through `DisjointnessPredicate` → this policy).
+
+    It is also the **deterministic prefix floor** every other policy is ANDed
+    against (`admissible_under_floor`): it is pure path algebra, forgery-proof,
+    and the unshadowable lower bound a plugin can never displace (`resolve_overlap_
+    policy` resolves built-ins first) — the overlap analogue of the unshadowable
+    `text` renderer / `abstain` judge. The floor it computes uses the kernel's
+    own ⅓ default (NOT the workspace's possibly-looser declared ratio): the floor
+    is the conservative bound, so loosening `ratio_max` in data can only widen the
+    *policy's* admit set, never the floor it is checked against. See
+    `admissible_under_floor`.
+    """
+
+    name = "prefix"
+
+    def overlaps(
+        self, requested_tree: list[str], lease_tree: list[str], config: object,
+    ) -> OverlapDecision:
+        ratio_max = _ratio_max_from_config(config)
+        return overlap_verdict(requested_tree, lease_tree, ratio_max=ratio_max)
+
+
+def _ratio_max_from_config(config: object) -> float:
+    """The soft-overlap tolerance to use, read off the config (data seam).
+
+    Reads ``config.overlap_ratio_max`` when present and a sane float in (0, 1];
+    otherwise the kernel default ⅓. Defensive on purpose — a hand-built test
+    config, a `None` config, or a malformed value all fall back to the default
+    rather than crashing the admission hot path (the warn-and-fall-back posture
+    every config axis takes). A non-positive or >1 value is ignored (a ratio
+    outside (0, 1] is meaningless for a shared/requested fraction)."""
+    raw = getattr(config, "overlap_ratio_max", None)
+    if raw is None:
+        return OVERLAP_RATIO_MAX
+    try:
+        val = float(raw)
+    except (TypeError, ValueError):
+        return OVERLAP_RATIO_MAX
+    if not (0.0 < val <= 1.0):
+        return OVERLAP_RATIO_MAX
+    return val
+
+
+# The unforgeable floor instance — pure, stateless, reused.
+_FLOOR = PrefixOverlapPolicy()
+
+
+def floor_decision(requested_tree: list[str], lease_tree: list[str]) -> OverlapDecision:
+    """The deterministic prefix-disjointness floor verdict for two known trees.
+
+    Computed with the **kernel default** ⅓ tolerance, NOT a workspace-declared
+    one — the floor is the conservative bound a policy is checked against, so it
+    must not itself be loosened by `dos.toml [overlap]`.
+
+    The load-bearing consequence — net admission is ``policy ∧ floor``, so with the
+    floor fixed at ⅓:
+
+      * **Tightening** ``[overlap] ratio_max`` below ⅓ *works*: the policy is the
+        stricter voice, the floor never interferes, net admit = the tighter ratio.
+      * **Loosening** ``[overlap] ratio_max`` above ⅓ is *capped at ⅓*: the policy
+        would admit up to the looser ratio, but the floor re-refuses anything past
+        ⅓, so net admit stays ⅓. This is DELIBERATE — ⅓ is a fixed SAFETY CEILING
+        an operator cannot raise with a config line (loosening is the dangerous
+        direction for false-admits, `docs/90 §2`). To genuinely admit a pair the
+        prefix rule refuses you need a *stricter sound floor* (the glob-intersection
+        floor, `docs/113 §3.1`), not a looser scalar — soundness is not a knob.
+
+    So the data knob tunes admission *downward* freely and is bounded *upward* by
+    the kernel floor — the same asymmetry the rest of the seam has (a swappable
+    scorer can only refuse-more)."""
+    return overlap_verdict(requested_tree, lease_tree, ratio_max=OVERLAP_RATIO_MAX)
+
+
+def admissible_under_floor(
+    policy: OverlapPolicy,
+    requested_tree: list[str],
+    lease_tree: list[str],
+    config: object,
+) -> OverlapDecision:
+    """Run ``policy`` for two known trees, AND-ed under the deterministic floor.
+
+    The structural soundness guarantee in one function. Returns an
+    `OverlapDecision` whose ``admissible`` is::
+
+        floor.admissible  AND  policy.admissible
+
+    so a policy can only ever move the verdict toward REFUSE relative to the
+    prefix floor:
+
+      * floor REFUSE → the floor verdict is returned regardless of the policy
+        (the dangerous cell — admitting a prefix-colliding pair — is unreachable;
+        the policy is not even able to express an admit that survives the AND).
+      * floor ADMIT, policy ADMIT → the policy verdict (it may carry a richer
+        reason; both agree it is safe).
+      * floor ADMIT, policy REFUSE → the policy's REFUSE (a stricter scorer caught
+        an overlap the prefix rule missed — the safe, more-refusing direction).
+      * policy raises / returns a non-`OverlapDecision` → the floor verdict alone
+        (fail-closed toward the prefix rule — today's behavior, never looser).
+
+    This is the ONE place `DisjointnessPredicate` consults a policy; it is what
+    makes "a swappable scorer can never admit a collision" a property of the
+    *shape of the computation*, not a property of the plugin behaving."""
+    floor = floor_decision(requested_tree, lease_tree)
+    # Floor refuses → no policy can admit. Return the floor verdict verbatim so the
+    # operator sees the unforgeable reason (and a hostile policy cannot even dilute
+    # the *message*, let alone the verdict).
+    if not floor.admissible:
+        return floor
+    # Floor admits → consult the policy, fail-closed to the floor on any misbehavior.
+    name = getattr(policy, "name", type(policy).__name__)
+    try:
+        decision = policy.overlaps(list(requested_tree), list(lease_tree), config)
+    except Exception as e:  # fail-closed: a policy that raises falls back to the floor
+        return OverlapDecision(
+            floor.verdict, floor.shared, floor.requested,
+            (f"overlap policy {name!r} raised ({e!r}) — using the deterministic "
+             f"prefix floor verdict ({floor.reason})."),
+        )
+    if not isinstance(decision, OverlapDecision):
+        # A policy that does not return our type cannot be trusted to admit; we
+        # never read a foreign object's `.admissible`, so no admit leaks through a
+        # wrong return type. Fall back to the floor.
+        return OverlapDecision(
+            floor.verdict, floor.shared, floor.requested,
+            (f"overlap policy {name!r} returned a {type(decision).__name__}, not "
+             f"an OverlapDecision — using the deterministic prefix floor verdict "
+             f"({floor.reason})."),
+        )
+    if decision.admissible:
+        # Both floor and policy admit. Return the policy's (possibly richer) verdict.
+        return decision
+    # Floor admits but policy refuses — the stricter scorer wins (refuse-more is
+    # the safe direction). Surface the policy's reason.
+    return decision
+
+
+# ---------------------------------------------------------------------------
+# Resolution — built-in first, then the `dos.overlap_policies` entry-point group.
+# ---------------------------------------------------------------------------
+
+# The entry-point group a workspace/researcher registers an overlap policy under.
+OVERLAP_POLICY_ENTRY_POINT_GROUP = "dos.overlap_policies"
+
+# The built-in policies, resolvable by name and UNSHADOWABLE by a plugin (a plugin
+# registering `prefix` cannot displace this one — built-ins resolve first). Only
+# the deterministic prefix scorer ships in the kernel; a model-backed or
+# import-graph policy lives in a driver/plugin.
+_BUILT_IN_POLICIES: dict[str, type] = {
+    PrefixOverlapPolicy.name: PrefixOverlapPolicy,
+}
+
+
+def _discover_entry_point_policies(*, _stderr=None) -> list[tuple[str, OverlapPolicy]]:
+    """Find overlap policies registered under the `dos.overlap_policies` group.
+
+    A policy plugin registers ``name = "pkg.module:PolicyClass"`` in its
+    ``[project.entry-points."dos.overlap_policies"]``. We load each, instantiate
+    it if it is a class, and return ``(entry_point_name, policy)`` pairs sorted by
+    name (stable, so `dos doctor` order is deterministic). A plugin that fails to
+    load is skipped with a one-line stderr note rather than crashing arbitration —
+    the same posture `_discover_entry_point_judges` / predicate discovery take."""
+    stderr = _stderr if _stderr is not None else sys.stderr
+    out: list[tuple[str, OverlapPolicy]] = []
+    try:
+        from importlib.metadata import entry_points
+    except Exception:  # pragma: no cover - importlib.metadata always present py3.11+
+        return out
+    try:
+        eps = entry_points(group=OVERLAP_POLICY_ENTRY_POINT_GROUP)
+    except TypeError:  # pragma: no cover - py<3.10 selectable-API fallback
+        eps = entry_points().get(OVERLAP_POLICY_ENTRY_POINT_GROUP, [])  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - defensive: never let discovery crash a call
+        return out
+    for ep in sorted(eps, key=lambda e: e.name):
+        try:
+            obj = ep.load()
+            policy = obj() if isinstance(obj, type) else obj
+        except Exception as e:  # pragma: no cover - depends on third-party plugin
+            print(
+                f"warning: overlap policy plugin {ep.name!r} failed to load ({e}); "
+                f"skipping",
+                file=stderr,
+            )
+            continue
+        out.append((ep.name, policy))
+    return out
+
+
+def resolve_overlap_policy(name: str, *, _stderr=None) -> OverlapPolicy:
+    """Resolve an overlap policy by name: built-ins first, then plugins.
+
+    Built-ins (`prefix`) resolve FIRST and cannot be shadowed by a plugin of the
+    same name — the trusted-floor guarantee, identical to `resolve_judge` /
+    `resolve_renderer`. An unknown name fails LOUD with the known list (it never
+    silently degrades to `prefix`, which would hide a typo'd `--policy`): the
+    caller asked for a specific scorer and getting a different one silently is
+    exactly the unannounced substitution the kernel refuses."""
+    if name in _BUILT_IN_POLICIES:
+        return _BUILT_IN_POLICIES[name]()
+    discovered = dict(_discover_entry_point_policies(_stderr=_stderr))
+    if name in discovered:
+        return discovered[name]
+    known = sorted(set(_BUILT_IN_POLICIES) | set(discovered))
+    raise ValueError(
+        f"unknown overlap policy {name!r}; known: {', '.join(known)}"
+    )
+
+
+def active_overlap_policy(*, config: object = None, _stderr=None) -> OverlapPolicy:
+    """The overlap policy a CALLER threads into the disjointness check.
+
+    Resolution: a workspace may name its policy in ``config.overlap_policy_name``
+    (the `dos.toml [overlap] policy` data field); absent that, the built-in
+    `prefix` floor scorer. Does ENTRY-POINT DISCOVERY (I/O) when a non-`prefix`
+    name is configured, so it is a CALL-BOUNDARY helper (the CLI's `cmd_arbitrate`,
+    `dos doctor`), never called inside the pure `arbitrate`. The pure default —
+    no config, or `prefix` — returns the built-in with no discovery, so the hot
+    path stays I/O-free, exactly as `built_in_predicates` does.
+
+    Like the predicate seam, the kernel's pure `arbitrate` never calls this; the
+    boundary resolves the policy and passes it in (or the built-in `prefix` floor
+    is used). So `arbitrate`'s default path is byte-identical to before the seam."""
+    name = getattr(config, "overlap_policy_name", None) if config is not None else None
+    if not name or name == PrefixOverlapPolicy.name:
+        return PrefixOverlapPolicy()
+    return resolve_overlap_policy(str(name), _stderr=_stderr)
+
+
+def active_overlap_policy_names(*, _stderr=None) -> list[str]:
+    """The names of every resolvable overlap policy (built-in + discovered) — what
+    `dos doctor` lists so an operator can see which scorers the arbiter could use
+    (the overlap analogue of "see the active predicates / judges")."""
+    built = list(_BUILT_IN_POLICIES)
+    discovered = [n for n, _p in _discover_entry_point_policies(_stderr=_stderr)]
+    return built + discovered