cctally 1.113.0 → 1.115.0

package/bin/_lib_account_protocol.py

@@ -0,0 +1,386 @@
+"""Pure account-bound protocol kernel (#825/#832, spec sections 5.1-5.4).
+
+One durable journal and one stats index are fenced by a durable
+``account_bound_cutover`` op and a per-record writer-generation stamp. This
+module owns:
+
+* the protocol constants (writer generation, op kinds, the cutover op id);
+* the stamp the shared append preparation applies to every record the current
+  binary writes;
+* the historical boundary the cutover op records, and its payload codec;
+* the admission predicate every accounting reader applies BEFORE it interprets
+  a record (ingest, rebuild, rederive, journal-repair, correction selection,
+  cache recovery and the deep doctor scans).
+
+"After the cutover" is a PHYSICAL journal position (segment and byte offset of
+a complete line), never ``at``, capture time or provider time. A record is
+historical when it lies inside the frozen complete-line extent the cutover op
+recorded for its segment; a segment absent from that map (a later month, or a
+bootstrap segment created after the cutover, which sorts FIRST in canonical
+order) is post-boundary in its entirety.
+
+The fence is Claude-scoped (operator Q5). Exclusion is the default: a
+post-boundary record without the current writer generation is admitted only
+when an explicit field its real producer writes proves it Codex-only. An
+unknown or unclassifiable record is excluded, never admitted by omission.
+
+Pure: no I/O, no clock, no SQLite.
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import re
+from typing import Mapping
+
+
+PROTOCOL_GENERATION = "account-bound-v1"
+WRITER_GENERATION_KEY = "wpg"
+CUTOVER_OP_KIND = "account_bound_cutover"
+CUTOVER_OP_ID = "account-bound-cutover-v1"
+LEGACY_SPOOL_ACTIVITY_KIND = "legacy_spool_activity"
+#: Spec revision 5 (section 7, operator decision on Codex design-fix-round-5
+#: Q4): the `legacy_spool_activity` reason of an incomplete inventory. Such an
+#: op records typed failure evidence and no digest, so it anchors no baseline.
+INVENTORY_INCOMPLETE_REASON = "inventory-incomplete"
+#: Fix round K12 (K11R-4; spec 5.5 step 6, 5.6 item 1(b) and section 7): the
+#: reason of the anchoring op the first complete inventory appends after a
+#: cutover that recorded inventory uncertainty and so anchored no baseline.
+#: It records the complete digest and ends that episode. Like every
+#: `legacy_spool_activity` op it is a trigger, but of the same uncertainty,
+#: never an observed legacy change, and it clears nothing (residual 6).
+INVENTORY_COMPLETE_REASON = "inventory-complete"
+#: The reasons whose unresolved markers an incomplete inventory left.
+INVENTORY_REASONS = (INVENTORY_INCOMPLETE_REASON, INVENTORY_COMPLETE_REASON)
+#: The operations an inventory can fail at (the evidence's ``operation``).
+INVENTORY_OPERATIONS = ("list", "stat", "read")
+
+#: The versioned successors of the two administrative op kinds whose
+#: previous-release validators require exact keys (spec 5.1). The previous
+#: release ignores an unknown op kind, so the current binary emits only these.
+PROTOCOL_RESOLUTION_V2_KIND = "journal_protocol_resolution_v2"
+WEEKLY_OBSERVATION_DECISION_V2_KIND = "claude_weekly_observation_decision_v2"
+
+#: Admission families. ``codex`` is the only family admitted without a stamp.
+FAMILIES = (
+    "claude-observation",
+    "claude-op",
+    "claude-event",
+    "administrative",
+    "protocol",
+    "codex",
+    "unknown",
+)
+
+ADMISSION_REASONS = ("no-cutover", "historical", "stamped", "codex-only",
+                     "excluded")
+
+_DIGEST_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+_CLAUDE_OP_KINDS = frozenset((
+    "account_observe", "account_label", "accounts_cutover",
+    "weekly_credit_floor", "sync_week",
+))
+_CODEX_OP_KINDS = frozenset((
+    "codex_file_account", "codex_window_attribution",
+    "codex_window_attribution_retract",
+))
+_ADMIN_OP_KINDS = frozenset((
+    "journal_protocol_resolution", "claude_weekly_observation_decision",
+    PROTOCOL_RESOLUTION_V2_KIND, WEEKLY_OBSERVATION_DECISION_V2_KIND,
+))
+_PROTOCOL_OP_KINDS = frozenset((CUTOVER_OP_KIND, LEGACY_SPOOL_ACTIVITY_KIND))
+_ADMIN_RECORD_TYPES = frozenset(("correction", "correction_batch"))
+_CLAUDE_EVT_KINDS = frozenset((
+    "snapshot_accept", "weekly_cost_snapshot", "week_reset", "five_hour_credit",
+    "five_hour_block_close", "percent_milestone", "five_hour_milestone",
+    "weekly_credit_effects", "projected", "project_budget", "meter_rate_change",
+))
+#: Evt kinds admitted without a stamp only when their payload proves a Codex
+#: quota source (``payload.source == "codex"``, the source every Codex quota
+#: identity carries and every Codex quota table filters on).
+_QUOTA_EVT_KINDS = frozenset(("quota_alert_arming", "quota_threshold_event"))
+
+
+@dataclasses.dataclass(frozen=True)
+class Coordinate:
+    """Physical journal position of a complete line: its segment name and the
+    byte offset at which the line STARTS."""
+
+    segment: str
+    offset: int
+
+
+@dataclasses.dataclass(frozen=True)
+class CutoverBoundary:
+    """The historical boundary recorded by the ``account_bound_cutover`` op.
+
+    ``segment``/``end_offset`` name where the op itself was appended: the
+    target segment and its complete-line end at that moment, which is the op's
+    own start offset. ``frozen_extents`` maps every
+    segment that existed before the op to its complete-line byte length at that
+    moment; only bytes inside those extents are historical.
+
+    Spec revision 5: when the establishment could not complete its legacy
+    spool inventory, the op records the uncertainty itself —
+    ``legacy_spool_inventory_failure`` holds the typed failure evidence and
+    ``legacy_spool_baseline_digest`` is None, so the op anchors no baseline
+    (the next complete inventory installs one under its own anchoring op).
+    """
+
+    segment: str
+    end_offset: int
+    frozen_extents: Mapping[str, int]
+    legacy_spool_baseline_digest: "str | None"
+    legacy_spool_inventory_failure: "Mapping[str, object] | None" = None
+
+
+@dataclasses.dataclass(frozen=True)
+class Admission:
+    admitted: bool
+    family: str
+    reason: str
+
+
+# --------------------------------------------------------------------------
+# writer-generation stamp
+# --------------------------------------------------------------------------
+
+def stamp(record: dict) -> dict:
+    """Return a shallow copy of ``record`` carrying the current writer
+    generation. Idempotent; refuses a record that already names a DIFFERENT
+    generation (a caller must never relabel another protocol's record). The
+    payload is never touched: the stamp is transport metadata."""
+    if not isinstance(record, dict):
+        raise ValueError("journal record must be a dict")
+    existing = record.get(WRITER_GENERATION_KEY)
+    if existing is not None and existing != PROTOCOL_GENERATION:
+        raise ValueError(
+            f"record already carries writer generation {existing!r}")
+    out = dict(record)
+    out[WRITER_GENERATION_KEY] = PROTOCOL_GENERATION
+    return out
+
+
+def is_stamped(record: dict) -> bool:
+    return (isinstance(record, dict)
+            and record.get(WRITER_GENERATION_KEY) == PROTOCOL_GENERATION)
+
+
+def strip_stamp(record: dict) -> dict:
+    """``record`` without its writer-generation field — the comparison shape
+    for semantic event duplicate/conflict classification."""
+    if not isinstance(record, dict) or WRITER_GENERATION_KEY not in record:
+        return record
+    return {k: v for k, v in record.items() if k != WRITER_GENERATION_KEY}
+
+
+# --------------------------------------------------------------------------
+# boundary
+# --------------------------------------------------------------------------
+
+def is_historical(coord: Coordinate, boundary: CutoverBoundary) -> bool:
+    extent = boundary.frozen_extents.get(coord.segment)
+    return extent is not None and coord.offset < extent
+
+
+def inventory_failure_evidence(*, path: str, operation: str,
+                               error: str, message: str = "") -> dict:
+    """The typed evidence of a failed legacy spool inventory (spec revision
+    5): the path, the failed operation and the error (its errno name). It is
+    diagnostic evidence only, never accounting input."""
+    evidence = {"path": str(path), "operation": str(operation),
+                "error": str(error)}
+    if message:
+        evidence["message"] = str(message)
+    if not is_inventory_failure(evidence):
+        raise ValueError(f"invalid inventory failure evidence {evidence!r}")
+    return evidence
+
+
+def is_inventory_failure(value) -> bool:
+    """Whether ``value`` is well-formed inventory failure evidence."""
+    if not isinstance(value, dict):
+        return False
+    if not (isinstance(value.get("path"), str)
+            and value.get("operation") in INVENTORY_OPERATIONS
+            and isinstance(value.get("error"), str) and value["error"]):
+        return False
+    message = value.get("message")
+    return message is None or isinstance(message, str)
+
+
+def boundary_payload(boundary: CutoverBoundary) -> dict:
+    """The camelCase payload fields of the cutover op (without ``kind``).
+    ``legacySpoolInventoryFailure`` is present only on a cutover that
+    recorded inventory uncertainty, so a complete cutover's bytes are
+    unchanged."""
+    payload = {
+        "segment": boundary.segment,
+        "endOffset": boundary.end_offset,
+        "frozenExtents": {k: boundary.frozen_extents[k]
+                          for k in sorted(boundary.frozen_extents)},
+        "legacySpoolBaselineDigest": boundary.legacy_spool_baseline_digest,
+    }
+    if boundary.legacy_spool_inventory_failure is not None:
+        payload["legacySpoolInventoryFailure"] = dict(
+            boundary.legacy_spool_inventory_failure)
+    return payload
+
+
+def _nonneg_int(value) -> bool:
+    return type(value) is int and value >= 0
+
+
+def boundary_from_op(op_record: dict) -> CutoverBoundary:
+    """Decode the boundary from a cutover op. Raises ``ValueError`` on any
+    shape failure: a malformed cutover op never yields a boundary."""
+    if not isinstance(op_record, dict) or op_record.get("t") != "op":
+        raise ValueError("cutover boundary must come from an op record")
+    payload = op_record.get("payload")
+    if not isinstance(payload, dict) or payload.get("kind") != CUTOVER_OP_KIND:
+        raise ValueError("record is not an account_bound_cutover op")
+    segment = payload.get("segment")
+    end_offset = payload.get("endOffset")
+    extents = payload.get("frozenExtents")
+    digest = payload.get("legacySpoolBaselineDigest")
+    if not isinstance(segment, str) or not segment:
+        raise ValueError("cutover boundary segment is invalid")
+    if not _nonneg_int(end_offset):
+        raise ValueError("cutover boundary endOffset is invalid")
+    if not isinstance(extents, dict) or not all(
+            isinstance(k, str) and k and _nonneg_int(v)
+            for k, v in extents.items()):
+        raise ValueError("cutover boundary frozenExtents is invalid")
+    failure = payload.get("legacySpoolInventoryFailure")
+    if failure is None:
+        if not isinstance(digest, str) or not _DIGEST_RE.match(digest):
+            raise ValueError("cutover boundary legacy spool digest is invalid")
+    else:
+        # Revision 5: an uncertain inventory records its evidence and NO
+        # digest; a digest beside failure evidence is malformed.
+        if not is_inventory_failure(failure) or digest is not None:
+            raise ValueError(
+                "cutover boundary legacy spool inventory failure is invalid")
+        failure = dict(failure)
+    return CutoverBoundary(
+        segment=segment,
+        end_offset=end_offset,
+        frozen_extents=dict(extents),
+        legacy_spool_baseline_digest=digest,
+        legacy_spool_inventory_failure=failure,
+    )
+
+
+# --------------------------------------------------------------------------
+# admission
+# --------------------------------------------------------------------------
+
+def _family(record: dict) -> tuple[str, bool]:
+    """``(family, codex_only)`` from an explicit allow-list per kind. Anything
+    not named here is ``("unknown", False)``."""
+    if not isinstance(record, dict):
+        return ("unknown", False)
+    t = record.get("t")
+    if t in _ADMIN_RECORD_TYPES:
+        return ("administrative", False)
+    payload = record.get("payload")
+    if not isinstance(payload, dict):
+        return ("unknown", False)
+    kind = payload.get("kind")
+    if t == "obs":
+        provider = record.get("provider")
+        if provider == "claude":
+            return ("claude-observation", False)
+        if provider == "codex" and kind == "quota_window_snapshot":
+            return ("codex", True)
+        return ("unknown", False)
+    if t == "op":
+        if kind in _CODEX_OP_KINDS:
+            return ("codex", True)
+        if kind in ("account_observe", "account_label"):
+            if payload.get("provider") == "codex":
+                return ("codex", True)
+            return ("claude-op", False)
+        if kind in _CLAUDE_OP_KINDS:
+            return ("claude-op", False)
+        if kind in _ADMIN_OP_KINDS:
+            return ("administrative", False)
+        if kind in _PROTOCOL_OP_KINDS:
+            return ("protocol", False)
+        return ("unknown", False)
+    if t == "evt":
+        if kind in _CLAUDE_EVT_KINDS:
+            return ("claude-event", False)
+        if kind == "budget":
+            if payload.get("vendor") == "codex":
+                return ("codex", True)
+            return ("claude-event", False)
+        if kind in _QUOTA_EVT_KINDS:
+            if payload.get("source") == "codex":
+                return ("codex", True)
+            return ("claude-event", False)
+        return ("unknown", False)
+    return ("unknown", False)
+
+
+def record_family(record: dict) -> str:
+    return _family(record)[0]
+
+
+def classify_admission(record: dict, coord: Coordinate,
+                       boundary: CutoverBoundary | None) -> Admission:
+    """The single admission predicate (spec 5.3).
+
+    Admitted when there is no cutover yet, when the record lies inside the
+    historical boundary, when it carries the current writer generation, or when
+    its family is proven Codex-only. Every other post-boundary record is
+    excluded."""
+    family, codex_only = _family(record)
+    if boundary is None:
+        return Admission(True, family, "no-cutover")
+    if is_historical(coord, boundary):
+        return Admission(True, family, "historical")
+    if is_stamped(record):
+        return Admission(True, family, "stamped")
+    if codex_only:
+        return Admission(True, family, "codex-only")
+    return Admission(False, family, "excluded")
+
+
+# --------------------------------------------------------------------------
+# excluded-population digest (spec section 8)
+# --------------------------------------------------------------------------
+
+_DIGEST_MODULUS = 1 << 256
+
+
+def _coordinate_term(coord: Coordinate) -> int:
+    data = f"{coord.segment}\x00{coord.offset}".encode("utf-8")
+    return int.from_bytes(hashlib.sha256(data).digest(), "big")
+
+
+def coordinate_population_digest(coords, base: str | None = None) -> str:
+    """An ORDER-INDEPENDENT digest over a set of physical coordinates: the sum
+    of each coordinate's sha256 modulo 2**256. ``base`` extends an earlier
+    digest incrementally, so an ingest cycle can add the coordinates it newly
+    excludes and a full scan reproduces the same value in any order."""
+    total = 0
+    if base is not None:
+        if not isinstance(base, str) or not _DIGEST_RE.match(base):
+            raise ValueError("coordinate population digest is invalid")
+        total = int(base[len("sha256:"):], 16)
+    for coord in coords:
+        total = (total + _coordinate_term(coord)) % _DIGEST_MODULUS
+    return "sha256:" + format(total, "064x")
+
+
+#: The record type of an inert positional placeholder for consumers that need
+#: a dict in an excluded record's slot. No reader recognises the type, so the
+#: selector, the pipeline and the legacy classifier all skip it while it still
+#: consumes the slot's sequence number.
+EXCLUDED_PLACEHOLDER_TYPE = "excluded"
+
+
+def excluded_placeholder() -> dict:
+    return {"t": EXCLUDED_PLACEHOLDER_TYPE}

package/bin/_lib_aggregators.py

@@ -46,6 +46,8 @@ import threading
 from dataclasses import dataclass
 from typing import Any, Callable, Iterable
 
+import _lib_codex_rollout_container as _rc
+
 
 def _cctally():
     """Resolve the current `cctally` module at call-time (spec §5.5)."""
@@ -687,6 +689,7 @@ def _session_path_parts(source_path: str) -> tuple[str, str, str]:
     keyed on ``(scope roots, source_path)``. Outside one the roots are
     resolved per call, which is the historic behaviour every CLI caller keeps.
     """
+    source_path = _rc.logical_path(source_path)
     scope = getattr(_CODEX_PATH_SCOPE, "scope", None)
     if scope is not None:
         return scope.parts(source_path)
@@ -713,6 +716,7 @@ def _session_path_parts_for_roots(
     files stay free of maintainer absolute paths), then basename. Direct-JSONL
     roots yield an id relative to <entry> itself (no sessions/ prefix).
     """
+    source_path = _rc.logical_path(source_path)
     p = pathlib.Path(source_path)
     rel: pathlib.PurePath | None = None
     for root in roots:

package/bin/_lib_cache_coverage.py

@@ -69,7 +69,19 @@ PROGRESS_KEY = "codex_journal_coverage_progress"
 #: `REASON_MALFORMED` and falls back to a full replay — the same outcome a bump
 #: would produce. A bump would additionally invalidate certificates written by
 #: an in-development binary that already carries the field, for no gain.
-COVERAGE_VERSION = 1
+#:
+#: Version 2 (#946; #825/#832 spec 4.7 revision 2, Codex design-fix-round-3
+#: Q5): every earlier writer took `appliedThrough` from an ingest cursor that
+#: could advance past a torn suffix. `_repair_torn_tail` then wrote a record
+#: across that coordinate, the next ingest started inside it and skipped it,
+#: and a contiguous advance certified it covered — a version-1 certificate can
+#: therefore claim coverage of an unapplied record at an endpoint that follows
+#: a newline, which no endpoint check can see. `prior_is_extendable` and
+#: `certificate_is_valid` both reject version 1, so the first current binary
+#: forces the full journal recovery and never extends or restamps one. A
+#: previous release reading a version-2 certificate rejects it the same way
+#: and replays (C2).
+COVERAGE_VERSION = 2
 
 #: Bumped whenever the journal-record-to-cache-row materialization changes —
 #: `_apply_quota_records`, `_apply_file_account_records`, or the §3.5 precedence

package/bin/_lib_cache_report.py

@@ -59,9 +59,13 @@ stable_sum = _import_stable_sum()
 
 
 def _import_pricing_kernel():
-    """Resolve the ``_lib_pricing`` symbols this kernel needs (#195/#413):
-    ``CACHE_WRITE_1H_MULTIPLIER`` (the derived 1-hour cache-write rate) and
-    ``claude_usage_dict`` (the single cost-feeding usage-dict constructor).
+    """Resolve the ``_lib_pricing`` symbols this kernel needs, returned in
+    this order: ``CACHE_WRITE_1H_MULTIPLIER`` (the derived 1-hour cache-write
+    rate, #195), ``_claude_fast_multiplier`` (the Fast-mode multiplier for a
+    model), ``claude_usage_dict`` (the single cost-feeding usage-dict
+    constructor, #413), ``TIERED_THRESHOLD`` (the legacy 200K marginal-tier
+    boundary) and ``_select_claude_request_card`` (the whole-request card
+    selector, #929).
 
     Same shape and same justification as ``_import_stable_sum`` above:
     ``_lib_pricing`` is a PURE stdlib leaf with no sibling imports, so binding
@@ -79,6 +83,7 @@ def _import_pricing_kernel():
             m._claude_fast_multiplier,
             m.claude_usage_dict,
             m.TIERED_THRESHOLD,
+            m._select_claude_request_card,
         )
     from pathlib import Path
     import importlib.util
@@ -99,11 +104,13 @@ def _import_pricing_kernel():
         m._claude_fast_multiplier,
         m.claude_usage_dict,
         m.TIERED_THRESHOLD,
+        m._select_claude_request_card,
     )
 
 
 (CACHE_WRITE_1H_MULTIPLIER, _claude_fast_multiplier,
- claude_usage_dict, DEFAULT_TIERED_THRESHOLD) = _import_pricing_kernel()
+ claude_usage_dict, DEFAULT_TIERED_THRESHOLD,
+ _select_claude_request_card) = _import_pricing_kernel()
 
 
 # ``DEFAULT_TIERED_THRESHOLD`` above is Anthropic's per-call >200K-tokens tier,
@@ -353,6 +360,7 @@ def _compute_entry_cache_dollars(
     cache_creation_tokens: int,
     cache_read_tokens: int,
     *,
+    input_tokens: int,
     pricing: dict,
     tiered_threshold: "int | None" = None,
     cache_1h_tokens: int | None = None,
@@ -384,12 +392,27 @@ def _compute_entry_cache_dollars(
     than in the signature. A default argument is evaluated once, at
     function-definition time, so a change to the module global would never
     reach the calls.
+
+    ``input_tokens`` (REQUIRED keyword, #929) is the entry's uncached input.
+    A whole-request card (Claude Haiku 5.5) selects ONE card per request from
+    its full prompt — input + cache creation + cache read — exactly as the
+    cost kernel does, so the card is selected once here, before any rate is
+    read. Selecting from the cache tokens alone would price a long request at
+    the base card. A legacy card is returned unchanged and every expression
+    below runs exactly as before.
     """
     if tiered_threshold is None:
         tiered_threshold = DEFAULT_TIERED_THRESHOLD
     p = _lookup_pricing(model, pricing) or {}
     if not p:
         return (0.0, 0.0, 0.0)
+    # The selected card carries no `_above_200k_tokens` key, so
+    # `_tiered_rate` returns its flat rates, and the wasted expression below
+    # is already the direct TTL form on the selected input rate.
+    p = _select_claude_request_card(
+        p, input_tokens=input_tokens,
+        cache_creation_tokens=cache_creation_tokens,
+        cache_read_tokens=cache_read_tokens)
 
     def _tiered_rate(tokens: int, base_key: str, tiered_key: str) -> float:
         """Blended $/token rate for a single-call token count under tiered pricing."""
@@ -527,7 +550,9 @@ def _aggregate_cache_by_day(
             )
         else:
             saved, wasted, net = _compute_entry_cache_dollars(
-                entry.model, create_tok, read_tok, pricing=pricing,
+                entry.model, create_tok, read_tok,
+                input_tokens=entry.usage.get("input_tokens", 0),   # #929
+                pricing=pricing,
                 # #195: the normalized flat key the ingest chokepoint writes;
                 # absent on a pre-split row -> None -> unchanged pricing.
                 cache_1h_tokens=entry.usage.get("cache_creation_1h_input_tokens"),
@@ -703,6 +728,7 @@ def _aggregate_cache_by_session(
                 entry.model,
                 entry.cache_creation_tokens,
                 entry.cache_read_tokens,
+                input_tokens=entry.input_tokens,   # #929
                 pricing=pricing,
                 # #195: getattr, not attribute access. This is a PURE kernel with
                 # a duck-typed entry contract — callers pass `_JoinedClaudeEntry`
@@ -1156,6 +1182,7 @@ def _aggregate_cache_breakdown(
                 getattr(e, "model", ""),
                 getattr(e, "cache_creation_tokens", 0),
                 getattr(e, "cache_read_tokens", 0),
+                input_tokens=getattr(e, "input_tokens", 0),   # #929
                 pricing=pricing,
                 # #195: getattr default None == split unknown, so an entry type
                 # that does not carry the split prices exactly as before.
@@ -1270,7 +1297,9 @@ def aggregate_by_day_project(
         create_tok = getattr(e, "cache_creation_tokens", 0)
         read_tok = getattr(e, "cache_read_tokens", 0)
         _s, _w, net = _compute_entry_cache_dollars(
-            model, create_tok, read_tok, pricing=pricing,
+            model, create_tok, read_tok,
+            input_tokens=getattr(e, "input_tokens", 0),   # #929
+            pricing=pricing,
             cache_1h_tokens=getattr(e, "cache_1h_tokens", None),   # #195
             speed=getattr(e, "speed", None),
         )

package/bin/_lib_cache_writer_lock.py

@@ -12,18 +12,28 @@ import fcntl
 import os
 import time
 from pathlib import Path
+from typing import Callable
 
 
 def acquire_ordered_flocks(
     locks: list[tuple[Path, int]],
     *,
     timeout: float | None = None,
+    on_failure: Callable[[Path, BaseException], None] | None = None,
 ) -> list[int] | None:
-    """Acquire ``(path, LOCK_SH|LOCK_EX)`` entries in caller-supplied order."""
+    """Acquire ``(path, LOCK_SH|LOCK_EX)`` entries in caller-supplied order.
+
+    ``on_failure(path, exc)``, when given, is told which lock the set lost to
+    before this returns None (``exc`` a ``BlockingIOError``: the lock was
+    held) or re-raises an ``OSError`` (an I/O error no holder caused), so a
+    caller can wait for exactly that lock's release (#825/#832).
+    """
     deadline = None if timeout is None else time.monotonic() + max(timeout, 0.0)
     held: list[int] = []
+    current: Path | None = None
     try:
         for path, mode in locks:
+            current = path
             fd = os.open(str(path), os.O_RDWR | os.O_CREAT, 0o600)
             os.fchmod(fd, 0o600)
             held.append(fd)
@@ -31,14 +41,18 @@ def acquire_ordered_flocks(
                 try:
                     fcntl.flock(fd, mode | fcntl.LOCK_NB)
                     break
-                except BlockingIOError:
+                except BlockingIOError as exc:
                     if deadline is None or time.monotonic() >= deadline:
                         release_cache_writer_flocks(held)
+                        if on_failure is not None:
+                            on_failure(path, exc)
                         return None
                     time.sleep(min(0.2, max(0.0, deadline - time.monotonic())))
         return held
-    except BaseException:
+    except BaseException as exc:
         release_cache_writer_flocks(held)
+        if on_failure is not None and current is not None and isinstance(exc, OSError):
+            on_failure(current, exc)
         raise
 
 
@@ -47,6 +61,7 @@ def acquire_cache_writer_flocks(
     provider_path: Path | None = None,
     *,
     timeout: float | None = None,
+    on_failure: Callable[[Path, BaseException], None] | None = None,
 ) -> list[int] | None:
     """Acquire global then optional provider flock, or return ``None``.
 
@@ -61,6 +76,7 @@ def acquire_cache_writer_flocks(
     return acquire_ordered_flocks(
         [(path, fcntl.LOCK_EX) for path in paths],
         timeout=timeout,
+        on_failure=on_failure,
     )