graphify-mesh 0.0.22__py3-none-any.whl

graphify_mesh/server/ranking.py

@@ -0,0 +1,209 @@
+"""WS5 fusion + ranking contract: pinned RRF constants, hub/DEPRECATED
+penalties, and MMR diversification. Every constant here is named and
+documented, per project style rule (no magic numbers).
+
+Fusion contract (plan WS5 bullet 3):
+  * Reciprocal Rank Fusion (RRF) combines however many retrievers actually
+    returned candidates this call (lexical always; vector only if the
+    generation has embeddings; structural/community always).
+  * Exact FQCN/label hits (resolved via the lexical index's `alias_exact`
+    table, see `retrieval.exact_alias_hits`) bypass fusion, the hub-degree
+    penalty, and MMR entirely — they are ranked first, deterministically.
+  * If a retriever has nothing to contribute this generation (most notably:
+    no embeddings at all, cold start / Ollama down during the sync run),
+    RRF simply sums over whichever retrievers DID return something — there
+    is no per-retriever normalization constant that assumes a fixed retriever
+    count, so "renormalizing over available retrievers" falls out for free;
+    the caller is responsible for surfacing the `degraded` flag (e.g.
+    `"embeddings_unavailable"`) so this is visible to the client, never
+    silently absorbed.
+  * Deterministic tie-breaking: candidates with an identical fused score are
+    ordered by their logical-ref string (`repo\x1fsource_file\x1flabel`),
+    so repeated identical queries return identical order regardless of dict
+    iteration order.
+"""
+
+from __future__ import annotations
+
+# --- RRF (Reciprocal Rank Fusion) ------------------------------------------
+
+# Standard RRF smoothing constant (Cormack et al. 2009's k=60 is the
+# widely-cited default; kept as a named, overridable constant rather than a
+# bare literal at each call site).
+RRF_K = 60
+
+# Per-retriever candidate depth: how many top-ranked candidates each of the
+# lexical/vector/structural retrievers contributes into the fusion pool
+# before RRF combines them. Kept well above the largest supported `k` so
+# fusion has enough material to diversify from.
+CANDIDATE_DEPTH_LEXICAL = 50
+CANDIDATE_DEPTH_VECTOR = 50
+CANDIDATE_DEPTH_STRUCTURAL = 50
+
+# --- Ranking penalties -------------------------------------------------
+
+# Hub/degree penalty: nodes above this total-degree threshold are generic
+# hubs (CacheKey/User/Where-style god-nodes that flooded every baseline
+# probe — see graphify/baseline-2026-07-20.md probes 2/11) and get
+# multiplicatively down-weighted rather than excluded outright (a real hit
+# that happens to be a hub should still be findable, just not favored).
+HUB_DEGREE_THRESHOLD = 50
+HUB_PENALTY_FACTOR = 0.5
+
+# DEPRECATED-path down-weight (baseline systemic failure #8: DEPRECATED
+# code dominated gamestream API results).
+DEPRECATED_PATH_MARKER = "/DEPRECATED/"
+DEPRECATED_PENALTY_FACTOR = 0.3
+
+# Confidence handling is an allowlist: only EXTRACTED edges are followed by
+# default in traversal (structural candidates, similar, neighbors). graphify
+# also emits AMBIGUOUS, scored below INFERRED, so a denylist of INFERRED alone
+# lets the weaker class through. Callers opt in to every non-EXTRACTED edge
+# via `include_inferred=True`. EXTRACTED is the graphify default confidence
+# class for edges that don't carry an explicit `confidence` attribute (see
+# graphify/export.py's `_CONFIDENCE_SCORE_DEFAULTS`).
+CONFIDENCE_EXTRACTED = "EXTRACTED"
+CONFIDENCE_INFERRED = "INFERRED"
+CONFIDENCE_AMBIGUOUS = "AMBIGUOUS"
+
+# --- MMR (maximal marginal relevance) diversification -----------------
+
+# Trade-off between relevance (fused score) and novelty vs already-selected
+# results. 1.0 = pure relevance (no diversification), 0.0 = pure novelty.
+MMR_LAMBDA = 0.7
+
+# --- Tool contracts -----------------------------------------------------
+
+MAX_K = 100
+DEFAULT_K = 10
+PAGE_SIZE = 20
+
+
+def edge_followable(edge: dict, include_inferred: bool) -> bool:
+    """True when traversal may follow `edge`: EXTRACTED (the default when the
+    edge carries no `confidence`), or any confidence once the caller opted in."""
+    return include_inferred or edge.get("confidence", CONFIDENCE_EXTRACTED) == CONFIDENCE_EXTRACTED
+
+
+def rrf_contribution(rank: int) -> float:
+    """`rank` is 0-indexed position within one retriever's ranked list."""
+    return 1.0 / (RRF_K + rank + 1)
+
+
+def fuse_rankings(rankings: dict[str, list[str]]) -> dict[str, float]:
+    """`rankings`: retriever name -> its ranked list of doc keys (best
+    first). Returns doc key -> summed RRF score. Retrievers that returned
+    nothing simply don't contribute — no fixed-N normalization assumption."""
+    scores: dict[str, float] = {}
+    for ranked in rankings.values():
+        for idx, key in enumerate(ranked):
+            scores[key] = scores.get(key, 0.0) + rrf_contribution(idx)
+    return scores
+
+
+def apply_penalties(
+    doc_key: str,
+    base_score: float,
+    degree_by_key: dict[str, int],
+    path_by_key: dict[str, str],
+) -> float:
+    """Multiplicative hub-degree + DEPRECATED-path penalties. Never applied
+    to exact-alias bypass hits (those skip this function entirely — see
+    `retrieval.rank_candidates`)."""
+    score = base_score
+    if degree_by_key.get(doc_key, 0) > HUB_DEGREE_THRESHOLD:
+        score *= HUB_PENALTY_FACTOR
+    path = path_by_key.get(doc_key, "") or ""
+    if DEPRECATED_PATH_MARKER in path:
+        score *= DEPRECATED_PENALTY_FACTOR
+    return score
+
+
+def _structural_similarity_proxy(key_a: str, key_b: str, path_by_key: dict[str, str]) -> float:
+    """Cheap, dependency-free doc-doc similarity proxy for MMR, used
+    instead of vector cosine so diversification still functions when
+    embeddings are unavailable (degraded mode, C9 cold start). Same source
+    file => high similarity (near-duplicate results from the same file);
+    otherwise 0. Deterministic and requires nothing beyond data already
+    loaded for ranking."""
+    path_a = path_by_key.get(key_a)
+    path_b = path_by_key.get(key_b)
+    if path_a and path_a == path_b:
+        return 0.9
+    return 0.0
+
+
+def mmr_select(
+    scored_candidates: list[tuple[str, float]],
+    path_by_key: dict[str, str],
+    k: int,
+    lam: float = MMR_LAMBDA,
+) -> list[str]:
+    """Greedy MMR selection over an already-scored candidate pool.
+    Deterministic: ties broken by the candidate's own key (sorted lexical-
+    ref string) at every selection step.
+
+    Incremental implementation: each remaining candidate carries a running
+    `max_sim` against the already-selected set, updated only against the
+    item selected in the previous step (max over a growing set == running
+    max), so each selection step is one O(n) pass instead of a full re-sort
+    that recomputes similarity against ALL selected items. Selection output
+    is identical to the previous sort-based implementation: the first pick
+    uses the pure-relevance `(-score, key)` order, every later pick
+    maximizes `mmr_value` with ties broken by ascending key — exactly the
+    ordering `sorted(pool, key=lambda c: (-mmr_value(c), c[0]))[0]`
+    produced."""
+    if k <= 0:
+        return []
+    if not scored_candidates:
+        return []
+
+    # Mutable pool entries: [key, score, running max_sim vs selected].
+    pool: list[list] = [[key, score, 0.0] for key, score in scored_candidates]
+    selected: list[str] = []
+
+    def _pop(index: int) -> list:
+        # O(1) removal: swap with the last entry. Pool order is irrelevant —
+        # every pick below scans the whole pool with an explicit
+        # deterministic tie-break, never relies on pool order.
+        entry = pool[index]
+        pool[index] = pool[-1]
+        pool.pop()
+        return entry
+
+    def _pick_first() -> None:
+        best_index = 0
+        best_rank = (-pool[0][1], pool[0][0])
+        for index in range(1, len(pool)):
+            rank = (-pool[index][1], pool[index][0])
+            if rank < best_rank:
+                best_rank = rank
+                best_index = index
+        selected.append(_pop(best_index)[0])
+
+    def _pick_next() -> None:
+        last_selected = selected[-1]
+        best_index = 0
+        best_rank: tuple[float, str] | None = None
+        for index, entry in enumerate(pool):
+            sim = _structural_similarity_proxy(entry[0], last_selected, path_by_key)
+            if sim > entry[2]:
+                entry[2] = sim
+            value = lam * entry[1] - (1 - lam) * entry[2]
+            rank = (-value, entry[0])
+            if best_rank is None or rank < best_rank:
+                best_rank = rank
+                best_index = index
+        selected.append(_pop(best_index)[0])
+
+    _pick_first()
+    while pool and len(selected) < k:
+        _pick_next()
+    return selected
+
+
+def deterministic_sort_key(logical_ref_key: str) -> str:
+    """Canonical tie-break key: the logical ref string itself
+    (`repo\x1fsource_file\x1fqualified_label`, same shape as
+    `overlay_refs.LogicalRef.to_key()`)."""
+    return logical_ref_key

graphify_mesh/server/retrieval.py

@@ -0,0 +1,343 @@
+"""WS5 candidate generation + fusion orchestration.
+
+Scope filtering happens INSIDE each `*_candidates` function, before any
+ranking/scoring is computed — never as a post-filter of an already-ranked
+list (see `scope.py` module docstring for why that ordering matters).
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import numpy as np
+
+from graphify_mesh.server import anchors, lexical_read, ranking
+from graphify_mesh.server.store import Generation
+from graphify_mesh.sync.lexical_index import normalize_alias_query, tokenize_text
+from graphify_mesh.sync.vectors import RepoVectors
+
+EmbedQueryFn = Callable[[str], list[float] | None]
+
+# Score carried by exact-alias bypass hits. It must dominate every fused
+# score (RRF sums stay below 1.0 even with all three retrievers agreeing)
+# while remaining a finite float: the score is serialized with `json.dumps`,
+# and `float("inf")` would emit the bare token `Infinity`, which strict JSON
+# parsers reject.
+EXACT_MATCH_SCORE = 1_000_000.0
+
+
+@dataclass
+class Hit:
+    key: str
+    repo: str
+    source_file: str
+    label: str
+    node_id: str
+    degree: int
+    score: float
+    match_type: str  # "exact" | "anchor" | "fused"
+    deprecated: bool
+
+
+@dataclass
+class RankedResult:
+    hits: list[Hit] = field(default_factory=list)
+    degraded: list[str] = field(default_factory=list)
+
+
+def exact_alias_hits(query: str, lexical: dict, repo_filter: frozenset[str] | None) -> list[str]:
+    """Exact FQCN/label bypass candidates (WS5 fusion contract): looked up
+    through the version-aware lexical reader, normalized with the SAME
+    normalization the index was built with (`normalize_alias_query`)."""
+    if not query or not query.strip():
+        return []
+    norm = normalize_alias_query(query.strip())
+    refs = lexical_read.alias_refs(lexical, norm)
+    keys = {key for repo, key in refs if repo_filter is None or repo in repo_filter}
+    return sorted(keys)
+
+
+def lexical_candidates(
+    query: str,
+    lexical: dict,
+    repo_filter: frozenset[str] | None,
+    depth: int = ranking.CANDIDATE_DEPTH_LEXICAL,
+) -> list[str]:
+    """Rank lexical candidates using version-aware postings and document metadata."""
+    tokens = tokenize_text(query)
+    if not tokens:
+        return []
+    total_docs = max(lexical_read.document_count(lexical), 1)
+    field_boosts = lexical.get("field_boosts", {})
+
+    scores: dict[str, float] = {}
+    for term in tokens:
+        triples = lexical_read.term_postings(lexical, term)
+        df = lexical_read.term_doc_freq(lexical, term) or 1
+        idf = math.log(1 + (total_docs / df))
+        for repo, key, field_name in triples:
+            if repo_filter is not None and repo not in repo_filter:
+                continue
+            if key is None:
+                continue
+            weight = field_boosts.get(field_name, 1.0)
+            scores[key] = scores.get(key, 0.0) + weight * idf
+
+    ranked = sorted(scores.items(), key=lambda kv: (-kv[1], kv[0]))
+    return [k for k, _ in ranked[:depth]]
+
+
+def _repo_scores(repo_vectors: RepoVectors, normalized_query: np.ndarray) -> np.ndarray:
+    """Per-repo cosine scores against an already-normalized query vector.
+    Mixed-dimension shard vs query carries no comparable signal (same rule
+    `cosine_similarity` applied per key) — every key in that repo scores 0
+    rather than being dropped from the pool, so it still tie-breaks by key
+    like the old per-key comparison did."""
+    if repo_vectors.dim != normalized_query.shape[0]:
+        return np.zeros(len(repo_vectors), dtype=np.float32)
+    return repo_vectors.normalized() @ normalized_query
+
+
+def _embeddings_degraded_marker(
+    embeddings: dict[str, RepoVectors], embed_query_fn: EmbedQueryFn
+) -> str:
+    """The `degraded` entry for a call where the vector retriever contributed
+    nothing.
+
+    Two very different situations used to collapse onto the same bare
+    `"embeddings_unavailable"` string: a generation that published no vectors
+    at all (a build/config problem) and a query-time embed call that failed
+    (a backend problem). A client could not tell them apart, which is the
+    whole reason a wedged backend looked like a misconfiguration for a day.
+
+    The bare marker is kept for the not-published case — `store` already
+    reports it that way for the same condition, and it stays the stable
+    string those checks match. A query-time failure instead reports
+    `"embeddings_unavailable:<reason>"`, taking the reason from the
+    embedder when it exposes one; a plain callable (the `EmbedQueryFn`
+    contract is only `str -> list[float] | None`) has no reason to give, so
+    it falls back to the bare marker rather than inventing one.
+    """
+    if not embeddings:
+        return "embeddings_unavailable"
+    reason_fn = getattr(embed_query_fn, "failure_reason", None)
+    if not callable(reason_fn):
+        return "embeddings_unavailable"
+    return f"embeddings_unavailable:{reason_fn()}"
+
+
+def vector_candidates(
+    query: str,
+    embeddings: dict[str, RepoVectors],
+    repo_filter: frozenset[str] | None,
+    embed_query_fn: EmbedQueryFn,
+    depth: int = ranking.CANDIDATE_DEPTH_VECTOR,
+) -> tuple[list[str], bool]:
+    """Returns (ranked keys, degraded). `degraded=True` means the vector
+    retriever contributed nothing this call (no embeddings published this
+    generation, or the query-embed call failed) — the caller renormalizes
+    fusion over whichever OTHER retrievers succeeded and must surface the
+    marker `_embeddings_degraded_marker` builds in the response's `degraded`
+    field, which distinguishes those two causes.
+
+    Scoring is matrix cosine similarity per repo: each `RepoVectors`
+    matrix's L2-normalized copy is cached on the instance
+    (`RepoVectors.normalized()`, computed once per process no matter how
+    many queries hit it this session) and multiplied against the
+    L2-normalized query vector in one `@` call — equivalent to calling
+    `cosine_similarity` per key, just batched over the whole repo instead
+    of a Python-level loop.
+    """
+    if not embeddings:
+        return [], True
+    vector = embed_query_fn(query)
+    if not vector:
+        return [], True
+
+    query_vec = np.asarray(vector, dtype=np.float32)
+    query_norm = float(np.linalg.norm(query_vec))
+    # Mirror `cosine_similarity`'s own zero-vector rule (score 0 rather
+    # than raising/NaN) via a safe divisor instead of skipping the whole
+    # query — a literal all-zero query vector should still tie-break by
+    # key, exactly like the old per-key comparison did.
+    safe_query_norm = query_norm if query_norm != 0.0 else 1.0
+    normalized_query = query_vec / safe_query_norm
+
+    # Per repo, pull only the top-`depth` scores via np.argpartition instead
+    # of materializing (key, score) for EVERY embedded node across all repos
+    # and full-sorting that one giant Python list per query. Boundary ties
+    # are kept (everything scoring >= the depth-th largest value), so the
+    # merged shortlist provably contains every key the old global sort could
+    # have selected — the final sort below then applies the exact same
+    # tie-break semantics (score desc, then key) on <= depth x n_repos
+    # candidates (plus ties).
+    scored: list[tuple[str, float]] = []
+    for repo_id, repo_vectors in embeddings.items():
+        if repo_filter is not None and repo_id not in repo_filter:
+            continue
+        if len(repo_vectors) == 0:
+            continue
+        scores = _repo_scores(repo_vectors, normalized_query)
+        n_rows = scores.shape[0]
+        if depth >= n_rows:
+            top_idx = np.arange(n_rows)
+        else:
+            partition = np.argpartition(scores, -depth)
+            threshold = scores[partition[-depth]]
+            top_idx = np.nonzero(scores >= threshold)[0]
+        for idx in top_idx:
+            scored.append((repo_vectors.keys[int(idx)], float(scores[int(idx)])))
+    scored.sort(key=lambda kv: (-kv[1], kv[0]))
+    return [k for k, _ in scored[:depth]], False
+
+
+def structural_candidates(
+    seed_keys: list[str],
+    generation: Generation,
+    repo_filter: frozenset[str] | None,
+    include_inferred: bool = False,
+    depth: int = ranking.CANDIDATE_DEPTH_STRUCTURAL,
+) -> list[str]:
+    """1-hop neighbors of `seed_keys` in the structural graph. Non-EXTRACTED
+    (INFERRED/AMBIGUOUS) edges are excluded by default (only EXTRACTED-confidence
+    edges count as traversal candidates unless the caller opts in) — baseline
+    systemic failure #4 (INFERRED edge pollution)."""
+    proximity: dict[str, int] = {}
+    for seed_key in seed_keys:
+        seed_id = generation.node_id_by_key.get(seed_key)
+        if seed_id is None:
+            continue
+        for neighbor_id, edge in generation.adjacency.get(seed_id, []):
+            if not ranking.edge_followable(edge, include_inferred):
+                continue
+            neighbor_key = generation.key_by_node_id.get(neighbor_id)
+            if neighbor_key is None:
+                continue
+            neighbor_node = generation.node_by_id.get(neighbor_id, {})
+            if repo_filter is not None and neighbor_node.get("repo") not in repo_filter:
+                continue
+            proximity[neighbor_key] = proximity.get(neighbor_key, 0) + 1
+
+    ranked = sorted(proximity.items(), key=lambda kv: (-kv[1], kv[0]))
+    return [k for k, _ in ranked[:depth]]
+
+
+def _hit_from_key(key: str, generation: Generation, score: float, match_type: str) -> Hit | None:
+    node_id = generation.node_id_by_key.get(key)
+    if node_id is None:
+        return None
+    node = generation.node_by_id.get(node_id, {})
+    source_file = node.get("source_file") or ""
+    return Hit(
+        key=key,
+        repo=node.get("repo", ""),
+        source_file=source_file,
+        label=node.get("label", ""),
+        node_id=node_id,
+        degree=generation.degree(node_id),
+        score=score,
+        match_type=match_type,
+        deprecated=ranking.DEPRECATED_PATH_MARKER in source_file,
+    )
+
+
+def rank(
+    query: str,
+    generation: Generation,
+    repo_filter: frozenset[str] | None,
+    k: int,
+    embed_query_fn: EmbedQueryFn,
+    include_inferred: bool = False,
+) -> RankedResult:
+    """Top-level WS5 search orchestration: exact-alias bypass, symbol
+    anchors (`anchors.py`), then lexical+vector+structural candidate
+    generation, RRF fusion, hub/DEPRECATED penalties, MMR diversification,
+    deterministic tie-break."""
+    k = max(1, min(k, ranking.MAX_K))
+    # Store-level degraded markers (reload rejections, embeddings stamp
+    # problems, ...) are merged into every tool response by the server layer
+    # (`GraphifyMeshServer.call_tool`), not read out of the manifest here.
+    degraded: list[str] = []
+
+    exact_keys = exact_alias_hits(query, generation.lexical, repo_filter)
+    exact_hits = [
+        h
+        for h in (_hit_from_key(k_, generation, EXACT_MATCH_SCORE, "exact") for k_ in exact_keys)
+        if h
+    ]
+    exact_hits.sort(key=lambda h: h.key)
+    # An alias shared by many nodes must not blow past the caller's `k`;
+    # truncating after the sort keeps which hits survive deterministic.
+    del exact_hits[k:]
+    selected_keys = {h.key for h in exact_hits}
+    remaining_slots = max(0, k - len(exact_hits))
+
+    anchor_hits: list[Hit] = []
+    anchor_key_set: set[str] = set()
+    if remaining_slots > 0:
+        for key in anchors.anchor_keys(query, generation, repo_filter, exclude=selected_keys):
+            hit = _hit_from_key(key, generation, anchors.ANCHOR_MATCH_SCORE, "anchor")
+            if hit:
+                anchor_hits.append(hit)
+        del anchor_hits[remaining_slots:]
+        # Anchors stay in the fused pool so MMR diversifies against them exactly
+        # as when they rank there on their own; they are dropped after selection.
+        anchor_key_set = {h.key for h in anchor_hits}
+        remaining_slots -= len(anchor_hits)
+
+    fused_hits: list[Hit] = []
+    if remaining_slots > 0:
+        lexical_ranked = lexical_candidates(query, generation.lexical, repo_filter)
+        vector_ranked, vec_degraded = vector_candidates(
+            query, generation.embeddings, repo_filter, embed_query_fn
+        )
+        if vec_degraded:
+            vec_marker = _embeddings_degraded_marker(generation.embeddings, embed_query_fn)
+            if vec_marker not in degraded:
+                degraded.append(vec_marker)
+
+        seed_for_structural = (exact_keys + lexical_ranked)[:10]
+        structural_ranked = structural_candidates(
+            seed_for_structural, generation, repo_filter, include_inferred=include_inferred
+        )
+
+        rankings = {
+            "lexical": lexical_ranked,
+            "vector": vector_ranked,
+            "structural": structural_ranked,
+        }
+        fused_scores = ranking.fuse_rankings(rankings)
+        for excluded in selected_keys:
+            fused_scores.pop(excluded, None)
+
+        degree_by_key = {
+            key: generation.degree(generation.node_id_by_key[key])
+            for key in fused_scores
+            if key in generation.node_id_by_key
+        }
+        path_by_key = {
+            key: generation.node_by_id.get(generation.node_id_by_key.get(key, ""), {}).get(
+                "source_file", ""
+            )
+            for key in fused_scores
+            if key in generation.node_id_by_key
+        }
+        penalized = [
+            (key, ranking.apply_penalties(key, score, degree_by_key, path_by_key))
+            for key, score in fused_scores.items()
+        ]
+        diversified_keys = ranking.mmr_select(
+            penalized, path_by_key, remaining_slots + len(anchor_key_set)
+        )
+        diversified_keys = [key for key in diversified_keys if key not in anchor_key_set][
+            :remaining_slots
+        ]
+        final_scores = dict(penalized)
+        for key in diversified_keys:
+            hit = _hit_from_key(key, generation, final_scores.get(key, 0.0), "fused")
+            if hit:
+                fused_hits.append(hit)
+
+    return RankedResult(hits=exact_hits + anchor_hits + fused_hits, degraded=sorted(set(degraded)))

graphify_mesh/server/rwlock.py

@@ -0,0 +1,61 @@
+"""Writer-preferring read/write lock.
+
+The shared daemon answers many reads against one loaded generation while a
+sync publish occasionally replaces it. Reads must not serialize behind each
+other, and the swap must not run while a read is in flight. Writer-preferring
+matters because reads are frequent: a reader-preferring lock would let a
+steady stream of queries postpone the reload indefinitely, and the daemon
+would keep serving a generation the pipeline already replaced.
+"""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+
+class ReadWriteLock:
+    def __init__(self) -> None:
+        self._cond = threading.Condition()
+        self._readers = 0
+        self._writer = False
+        self._waiting_writers = 0
+
+    @contextmanager
+    def read(self) -> Iterator[None]:
+        with self._cond:
+            while self._writer or self._waiting_writers:
+                self._cond.wait()
+            self._readers += 1
+        try:
+            yield
+        finally:
+            with self._cond:
+                self._readers -= 1
+                if self._readers == 0:
+                    self._cond.notify_all()
+
+    @contextmanager
+    def write(self) -> Iterator[None]:
+        with self._cond:
+            self._waiting_writers += 1
+            try:
+                while self._writer or self._readers:
+                    self._cond.wait()
+                self._writer = True
+            finally:
+                self._waiting_writers -= 1
+                # If `wait()` itself raised before granting the writer (e.g. an
+                # injected exception, or interpreter shutdown), threads already
+                # blocked in `wait()` would otherwise never be woken by this
+                # writer's exit — nothing else releases them. Notifying here
+                # too is a no-op cost on the normal path (readers/writers just
+                # re-check their own condition and wait again if not runnable).
+                self._cond.notify_all()
+        try:
+            yield
+        finally:
+            with self._cond:
+                self._writer = False
+                self._cond.notify_all()