cctally 1.114.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_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,
     )
 
 

package/bin/_lib_clone_copy.py

@@ -0,0 +1,142 @@
+"""Clone-first file and tree copies (stdlib only; #940 D2, spec §6.7).
+
+On APFS, ``fclonefileat(2)`` gives a copy that shares the source's blocks
+until either side is written, so a copy of a large test scaffold writes no
+data. This module takes that clone wherever it can and a real copy wherever
+it cannot, and otherwise behaves exactly as the stdlib copier it stands in
+for:
+
+- :func:`copy2` is ``shutil.copy2`` for the same arguments: a directory
+  destination keeps the source's basename, ``follow_symlinks=False`` copies a
+  link as a link, the same file raises ``shutil.SameFileError``, and an
+  existing destination is overwritten in place (same inode), which a clone
+  cannot do, so that case is a real copy. Metadata is ``shutil.copystat``'s,
+  applied after the clone as after a copy.
+- :func:`copytree` is ``shutil.copytree`` with :func:`copy2` as its file
+  copier, so symlink policy, ignore lists, dangling-link errors and
+  destination collisions are the stdlib's own code.
+
+A clone is attempted only on Darwin. An unsupported filesystem, a
+cross-volume destination, a missing ``fclonefileat`` and any non-Darwin
+platform take the real copy; any other error (EIO, ENOSPC, EACCES, …)
+propagates and is never retried as a copy. A clone is never a hardlink: the
+copy is a new inode with a link count of one.
+
+The optional ``counts`` mapping is incremented under ``"clone"`` or
+``"copy"`` per file, so a caller or a measurement can see which path ran.
+This module is public and imports nothing outside the standard library.
+
+It binds ``fclonefileat`` itself rather than importing the binding in
+``bin/_lib_remote_staging.py`` (#940 D-2 F17): that module is private, so it
+is absent from the public tree that this module and its public callers ship
+in, and a public module may not import it. The staging module may import
+from this one instead (spec §6.7).
+"""
+
+from __future__ import annotations
+
+import ctypes
+import errno
+import os
+import shutil
+import stat
+import sys
+
+# Errors that mean "this filesystem or this pair of volumes cannot clone",
+# never "the data could not be written". EEXIST is a destination created
+# after the existence check: `shutil.copy2` overwrites it, and so do we.
+_FALLBACK_ERRNOS = frozenset(
+    code for code in (
+        getattr(errno, "ENOTSUP", None), getattr(errno, "EOPNOTSUPP", None),
+        errno.ENOSYS, errno.EXDEV, errno.EINVAL, errno.EPERM, errno.EEXIST)
+    if code is not None)
+
+_AT_FDCWD = -2            # Darwin's AT_FDCWD
+_CLONE_NOOWNERCOPY = 0x0002  # leave ownership to the caller, as a copy does
+
+_LIBC_CLONE = []  # the resolved fclonefileat, once looked up
+# The platform this module decides on; a test sets it here instead of
+# patching the interpreter-wide ``sys.platform`` (#940 D-2 F16).
+_PLATFORM = sys.platform
+
+
+def _fclonefileat():
+    """The C ``fclonefileat`` on Darwin, else None."""
+    if _PLATFORM != "darwin":
+        return None
+    if not _LIBC_CLONE:
+        libc = ctypes.CDLL(None, use_errno=True)
+        clone = getattr(libc, "fclonefileat", None)
+        if clone is not None:
+            clone.argtypes = (ctypes.c_int, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint32)
+            clone.restype = ctypes.c_int
+        _LIBC_CLONE.append(clone)
+    return _LIBC_CLONE[0]
+
+
+def _clone_fd(source_fd: int, destination: str) -> None:
+    """Clone the open regular file `source_fd` to the new path `destination`."""
+    clone = _fclonefileat()
+    if clone is None:
+        raise OSError(errno.ENOTSUP, "fclonefileat is unavailable", destination)
+    if clone(source_fd, _AT_FDCWD, os.fsencode(os.path.abspath(destination)),
+             _CLONE_NOOWNERCOPY) != 0:
+        code = ctypes.get_errno()
+        raise OSError(code, os.strerror(code), destination)
+
+
+def _count(counts, method: str) -> None:
+    if counts is not None:
+        counts[method] = counts.get(method, 0) + 1
+
+
+def copy2(src, dst, *, follow_symlinks: bool = True, counts=None):
+    """``shutil.copy2(src, dst)``, by clone where the filesystem allows it.
+
+    Returns the destination path, as ``shutil.copy2`` does.
+    """
+    if os.path.isdir(dst):
+        dst = os.path.join(dst, os.path.basename(src))
+    if (not follow_symlinks and os.path.islink(src)) or os.path.lexists(dst):
+        # A link copied as a link, or a destination to overwrite in place.
+        result = shutil.copy2(src, dst, follow_symlinks=follow_symlinks)
+        _count(counts, "copy")
+        return result
+    try:
+        fd = os.open(src, os.O_RDONLY | getattr(os, "O_CLOEXEC", 0))
+    except OSError:
+        # The stdlib's own error for this source (missing, unreadable, …).
+        return shutil.copy2(src, dst, follow_symlinks=follow_symlinks)
+    try:
+        if not stat.S_ISREG(os.fstat(fd).st_mode):
+            # A FIFO, a device or a directory: the stdlib decides.
+            os.close(fd)
+            fd = -1
+            return shutil.copy2(src, dst, follow_symlinks=follow_symlinks)
+        try:
+            _clone_fd(fd, dst)
+        except OSError as exc:
+            if exc.errno not in _FALLBACK_ERRNOS:
+                raise
+            result = shutil.copy2(src, dst, follow_symlinks=follow_symlinks)
+            _count(counts, "copy")
+            return result
+        shutil.copystat(src, dst, follow_symlinks=follow_symlinks)
+        _count(counts, "clone")
+        return dst
+    finally:
+        if fd >= 0:
+            os.close(fd)
+
+
+def copytree(src, dst, symlinks: bool = False, ignore=None,
+             ignore_dangling_symlinks: bool = False, dirs_exist_ok: bool = False,
+             *, counts=None):
+    """``shutil.copytree`` with :func:`copy2` as its file copier."""
+    def copier(source, destination):
+        return copy2(source, destination, counts=counts)
+
+    return shutil.copytree(src, dst, symlinks=symlinks, ignore=ignore,
+                           copy_function=copier,
+                           ignore_dangling_symlinks=ignore_dangling_symlinks,
+                           dirs_exist_ok=dirs_exist_ok)