chtypes 2.0.0.dev6__py3-none-any.whl → 2.0.0.dev7__py3-none-any.whl

chtypes/__init__.py

@@ -98,7 +98,7 @@ from .errors import (
     UsageError,
 )
 from .library import Block, Filter, Library, Schema, Server, open_unverified
-from .registry import FetchOptions, Registry, Resolved, TrustedKey, cache_root, search_dirs
+from .registry import FetchOptions, Registry, Resolved, cache_root, search_dirs
 from .results import (
     AtMergeEntry,
     BatchResult,
@@ -201,7 +201,6 @@ __all__ = [
     "Span",
     "Status",
     "Transform",
-    "TrustedKey",
     "UnsupportedError",
     "UsageError",
     "Value",

chtypes/__main__.py

@@ -6,6 +6,10 @@
     chtypes verify [--cache <dir>] [--strict]   re-verify every installed build
     chtypes list   [--cache <dir>] [--offline] [--strict]
     chtypes where  [--cache <dir>] [--strict] [--all]   the cache root; --all: every search dir
+    chtypes resolve <spelling> [--json] [--cache <dir>] [--offline] [--strict]
+                   the build and manifest each platform resolves to, verified; installs nothing
+    chtypes prune  [--line <line>] [--keep <n>] [--dry-run] [--cache <dir>] [--strict]
+                   remove the builds of each line newer ones supersede, keeping the newest n
 
 A spelling is `26.8`, `26.8.15` or `26.8.15.10`. Exit statuses come from the
 `errors` table of spec/fetch-v1/constants.json (generated into the fetch layer
@@ -33,6 +37,7 @@ from collections.abc import Sequence
 
 from . import __version__ as chtypes_version
 from . import _ocifetch as fetch_layer
+from ._codes import CODE_ARTIFACT_CORRUPT
 from ._ocifetch import _channel
 from ._ocifetch import _constants as C
 from ._ocifetch._ensure import _translate_transport_error, detect_host_platform, missing_notes
@@ -41,6 +46,7 @@ from ._ocifetch._faults import probe_roots
 from ._ocifetch._http import FetchPolicy, RetryPolicy, TransportError, fetch_from_bases
 from ._ocifetch._layout import resolve_cache_root, search_roots
 from ._ocifetch._lock import load_lock
+from ._ocifetch._prune import is_line
 from .errors import ChtypesError
 from .registry import FetchOptions
 
@@ -50,7 +56,7 @@ EXIT_OK = 0
 EXIT_USAGE = 2
 # A failure that carries no code from the table (a lock file that cannot be
 # read, an interrupted run): the status the table gives its verification codes.
-_EXIT_FALLBACK = C.ERROR_EXIT_CODES["CHTYPES_ARTIFACT_CORRUPT"]
+_EXIT_FALLBACK = C.ERROR_EXIT_CODES[CODE_ARTIFACT_CORRUPT]
 _EXIT_INTERRUPTED = 130
 
 
@@ -153,7 +159,7 @@ def build_parser() -> argparse.ArgumentParser:
     listing = sub.add_parser(
         "list",
         help="what is installed, and what the registry publishes",
-        description="What is installed, and the version tags the registry publishes.",
+        description="What is installed, and the lines the registry publishes.",
     )
     cache_option(listing)
     listing.add_argument(
@@ -173,6 +179,55 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="every directory searched, in order, the cache root first (one per line)",
     )
+
+    resolving = sub.add_parser(
+        "resolve",
+        help="the build and manifest each platform resolves to, verified; installs nothing",
+        description=(
+            "What a line or version resolves to on every platform the registry offers, "
+            "each signature verified, with no layer downloaded (docs/guides/fetch-v1.md section 3)."
+        ),
+    )
+    resolving.add_argument(
+        "spelling",
+        metavar="<spelling>",
+        help="26.8, 26.8.15 or 26.8.15.10 (no v prefix, no channel suffix)",
+    )
+    resolving.add_argument(
+        "--json",
+        action="store_true",
+        help="print one JSON array, one object per platform, instead of one line per platform",
+    )
+    cache_option(resolving)
+    resolving.add_argument(
+        "--offline",
+        action="store_true",
+        help="answer from the cache; no network (or set CHTYPES_OFFLINE=1)",
+    )
+
+    pruning = sub.add_parser(
+        "prune",
+        help="remove the builds of each line newer ones supersede, keeping the newest n",
+        description=(
+            "Remove the installed builds of each line that newer installed builds of the same line "
+            "and platform supersede, keeping the newest n, and never one a running process holds "
+            "(docs/guides/fetch-v1.md section 1)."
+        ),
+    )
+    pruning.add_argument(
+        "--line", metavar="<line>", help="prune only this line, such as 26.8 (default: every line)"
+    )
+    pruning.add_argument(
+        "--keep",
+        metavar="<n>",
+        type=int,
+        default=1,
+        help="how many of each line's newest builds to keep, per platform (at least 1; default 1)",
+    )
+    pruning.add_argument(
+        "--dry-run", action="store_true", help="print what would be removed, and remove nothing"
+    )
+    cache_option(pruning)
     return parser
 
 
@@ -198,13 +253,15 @@ def _options(args: argparse.Namespace, *, platform: str | None = None):
     return fetch._to_options(platform)
 
 
-_LINE_SPELLING = re.compile(r"^[0-9]+\.[0-9]+$")
+# The published lines: exactly two parts, no leading zeros (Go's `lineTag`).
+_LINE_SPELLING = re.compile(r"^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$")
 
 
 def _published_tags(options) -> list[str]:
-    """The registry's `tags/list`, kept to the tags that are v1 version spellings
-    (`spelling.regex`): the referrers fallback tags (`sha256-<hex>`) and anything
-    else a repository carries are not versions."""
+    """The registry's `tags/list`, kept to the published lines (two-part tags),
+    in numeric order: three- and four-part versions, aliases, the referrers
+    fallback tags (`sha256-<hex>`) and anything else a repository carries are
+    dropped (docs/guides/fetch-v1.md section 3)."""
     try:
         resp = fetch_from_bases(
             options.resolved_bases(),
@@ -221,7 +278,7 @@ def _published_tags(options) -> list[str]:
         tags = json.loads(resp.body.decode("utf-8")).get("tags") or []
     except (ValueError, AttributeError) as exc:
         raise ArtifactCorruptError(f"chtypes: tags/list was not a tag list ({exc})") from exc
-    keep = [t for t in tags if isinstance(t, str) and re.fullmatch(C.SPELLING_REGEX, t)]
+    keep = [t for t in tags if isinstance(t, str) and _LINE_SPELLING.fullmatch(t)]
     return sorted(set(keep), key=lambda t: tuple(int(p) for p in t.split(".")))
 
 
@@ -250,7 +307,7 @@ def _cmd_fetch(args: argparse.Namespace) -> int:
             lock = load_lock(options.lock_path)
             spellings = list(lock.requests)
         else:
-            spellings = [t for t in _published_tags(options) if _LINE_SPELLING.match(t)]
+            spellings = _published_tags(options)
             if not spellings:
                 _say("chtypes: the registry publishes no lines")
     else:
@@ -297,7 +354,7 @@ def _cmd_verify(args: argparse.Namespace) -> int:
             _say(f"chtypes: FAILED {r.version} {r.platform} {r.dir}: {r.detail}")
     if failed:
         _say(f"chtypes: {failed} of {len(results)} installed build(s) FAILED verification")
-        return C.ERROR_EXIT_CODES["CHTYPES_ARTIFACT_CORRUPT"]
+        return C.ERROR_EXIT_CODES[CODE_ARTIFACT_CORRUPT]
     return EXIT_OK
 
 
@@ -328,7 +385,55 @@ def _cmd_where(args: argparse.Namespace) -> int:
     return EXIT_OK
 
 
-_COMMANDS = {"fetch": _cmd_fetch, "verify": _cmd_verify, "list": _cmd_list, "where": _cmd_where}
+def _cmd_resolve(args: argparse.Namespace) -> int:
+    options = _options(args)
+    request = fetch_layer.Request(args.spelling)  # a spelling error: usage, before any I/O
+    rows, warnings = fetch_layer.resolve(request, options)
+    for warning in warnings:
+        _say(f"chtypes: warning: {warning}")
+    if args.json:
+        doc = [
+            {"platform": r.platform, "version": r.version, "build": r.build, "manifest": r.manifest}
+            for r in rows
+        ]
+        sys.stdout.write(json.dumps(doc, separators=(",", ":")) + "\n")
+    else:
+        for r in rows:
+            sys.stdout.write(f"resolved {r.version} {r.platform} {r.build} {r.manifest}\n")
+    sys.stdout.flush()
+    return EXIT_OK
+
+
+def _cmd_prune(args: argparse.Namespace) -> int:
+    if args.keep < 1:
+        raise ValueError(f"chtypes: --keep is at least 1, not {args.keep}")
+    if args.line is not None and not is_line(args.line):
+        raise ValueError(f"chtypes: --line takes a two-part line such as 26.8, not {args.line!r}")
+    options = _options(args)
+    results = fetch_layer.prune(options, line=args.line, keep=args.keep, dry_run=args.dry_run)
+    removed = 0
+    for r in results:
+        if r.in_use:
+            word = "in-use"
+        else:
+            removed += 1
+            word = "would-prune" if args.dry_run else "pruned"
+        sys.stdout.write(f"{word} {r.version} {r.platform} {r.dir}\n")
+    sys.stdout.flush()
+    _say_notes(options)
+    root = resolve_cache_root(args.cache)
+    _say(f"chtypes: {'would prune' if args.dry_run else 'pruned'} {removed} build(s) under {root}")
+    return EXIT_OK
+
+
+_COMMANDS = {
+    "fetch": _cmd_fetch,
+    "verify": _cmd_verify,
+    "list": _cmd_list,
+    "where": _cmd_where,
+    "resolve": _cmd_resolve,
+    "prune": _cmd_prune,
+}
 
 
 def main(argv: Sequence[str] | None = None) -> int:

chtypes/_abi2/_errors.py

@@ -15,8 +15,8 @@ from chtypes.errors import (
     SchemaError,
     UnsupportedError,
     UsageError,
-    misuse,
 )
+from chtypes.errors import _misuse as misuse
 
 __all__ = [
     "ArtifactCorruptError",

chtypes/_codes.py

@@ -0,0 +1,23 @@
+# Code generated by scripts/fetch-v1/gen-constants.py from
+# spec/fetch-v1/constants.json. DO NOT EDIT.
+# Source sha256: 82afa8d6cba96c10b5945c6f7c1c8360a504cc8ac6231e74017cc6c20b908df6
+"""The shared error codes (docs/guides/fetch-v1.md §8), one per entry of the
+fetch constants' `errors`, in their order. `chtypes.errors` re-exports them
+(docs/reference/bindings-v1.md §4, the codes)."""
+
+from __future__ import annotations
+
+from typing import Final
+
+CODE_ARTIFACT_MISSING: Final[str] = "CHTYPES_ARTIFACT_MISSING"
+CODE_ARTIFACT_UNTRUSTED: Final[str] = "CHTYPES_ARTIFACT_UNTRUSTED"
+CODE_ARTIFACT_CORRUPT: Final[str] = "CHTYPES_ARTIFACT_CORRUPT"
+CODE_ARTIFACT_PINNED: Final[str] = "CHTYPES_ARTIFACT_PINNED"
+CODE_ARTIFACT_UNPUBLISHED: Final[str] = "CHTYPES_ARTIFACT_UNPUBLISHED"
+CODE_SOURCE_UNREACHABLE: Final[str] = "CHTYPES_SOURCE_UNREACHABLE"
+CODE_SOURCE_UNAUTHORIZED: Final[str] = "CHTYPES_SOURCE_UNAUTHORIZED"
+CODE_SOURCE_FORBIDDEN: Final[str] = "CHTYPES_SOURCE_FORBIDDEN"
+CODE_SOURCE_INCOMPATIBLE: Final[str] = "CHTYPES_SOURCE_INCOMPATIBLE"
+CODE_ARTIFACT_INCOMPATIBLE: Final[str] = "CHTYPES_ARTIFACT_INCOMPATIBLE"
+CODE_CACHE_UNUSABLE: Final[str] = "CHTYPES_CACHE_UNUSABLE"
+CODE_SOURCE_RETIRED: Final[str] = "CHTYPES_SOURCE_RETIRED"

chtypes/_decode.py

@@ -39,7 +39,8 @@ from ._abi2._vocab import (
     Source,
     Verdict,
 )
-from .errors import ArtifactCorruptError, internal
+from .errors import ArtifactCorruptError
+from .errors import _internal as internal
 from .results import (
     AtMergeEntry,
     BatchResult,

chtypes/_guard.py

@@ -14,7 +14,7 @@ import threading
 from collections.abc import Callable
 from types import TracebackType
 
-from .errors import misuse
+from .errors import _misuse as misuse
 
 __all__ = ["CloseGuard"]
 

chtypes/_input.py

@@ -14,7 +14,7 @@ import json
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 
-from .errors import misuse
+from .errors import _misuse as misuse
 
 __all__ = ["BytesIn", "ServerProfile", "Settings"]
 

chtypes/_ocifetch/__init__.py

@@ -6,7 +6,8 @@ logic lives in sibling modules. The seam (docs/guides/fetch-v1.md "The seam")
 is the only surface anything outside this package may use: `ensure`,
 `resolve_installed`, `list_installed`, `verify_installed` and
 `fetch_signed`, plus the `Request`/`Options`/`Resolved`/
-`VerifyResult` shapes they take and return. Every other module here
+`VerifyResult` shapes they take and return; and beside it the CLI's `resolve`
+and `prune` and the registry's in-use `hold` (§1, "In use"). Every other module here
 (`_http`, `_oci`, `_referrers`, `_dsse`, `_unpack`, `_layout`,
 `_lock`, `_errors`) is a private implementation detail of `_ensure`.
 
@@ -30,15 +31,25 @@ from chtypes._ocifetch._ensure import (
     resolve_installed,
     verify_installed,
 )
+from chtypes._ocifetch._hold import hold
+from chtypes._ocifetch._prune import Superseded, prune
+from chtypes._ocifetch._resolve import PlatformOutcome, Resolution, resolve, resolve_each
 
 __all__ = [
     "Options",
+    "PlatformOutcome",
     "Request",
+    "Resolution",
     "Resolved",
+    "Superseded",
     "VerifyResult",
     "ensure",
     "fetch_signed",
+    "hold",
     "list_installed",
+    "prune",
+    "resolve",
+    "resolve_each",
     "resolve_installed",
     "verify_installed",
 ]

chtypes/_ocifetch/_dsse.py

@@ -21,6 +21,7 @@ import base64
 import hashlib
 import json
 import os
+from collections.abc import Sequence
 from dataclasses import dataclass
 
 from chtypes import _ed25519
@@ -86,12 +87,21 @@ def env_trusted_keys() -> tuple[TrustedKey, ...] | None:
     items = [part.strip() for part in raw.split(",") if part.strip()]
     if not items:
         return None
+    return trusted_keys_from_hex(items, C.ENV_TRUSTED_KEYS_NAME)
+
+
+def trusted_keys_from_hex(items: Sequence[str], where: str) -> tuple[TrustedKey, ...]:
+    """Raw 32-byte ed25519 public keys, each as 64 hex digits (the
+    `CHTYPES_TRUSTED_KEYS` spelling, and the `trusted_keys` option's, as in
+    every binding), as trust-list records whose key id is the generated
+    constants' algorithm, sha256-first16hex of the raw key. A bad key is a
+    ValueError naming `where`."""
     keys = []
     for item in items:
         try:
-            public = _hex_to_bytes(item)
+            public = _hex_to_bytes(item.strip())
         except ValueError as exc:
-            raise ValueError(f"chtypes: {C.ENV_TRUSTED_KEYS_NAME} holds a bad key: {exc}") from None
+            raise ValueError(f"chtypes: {where} holds a bad key: {exc}") from None
         keys.append(TrustedKey(keyid=hashlib.sha256(public).hexdigest()[:16], public_key=public))
     return tuple(keys)
 

chtypes/_ocifetch/_ensure.py

@@ -867,7 +867,13 @@ def _ensure_floating(
     assert record is not None
 
     def _add_entry(doc: dict) -> dict:
-        entries = [*(doc.get("manifests") or []), {"digest": platform_desc.digest}]
+        entries = list(doc.get("manifests") or [])
+        # One entry per manifest digest: a re-install, or a concurrent one that
+        # landed first, never writes a second (public issue #487).
+        if not any(
+            isinstance(e, dict) and e.get("digest") == platform_desc.digest for e in entries
+        ):
+            entries.append({"digest": platform_desc.digest})
         return {**doc, "manifests": entries}
 
     try:
@@ -899,6 +905,82 @@ def _ensure_floating(
     return resolved
 
 
+def _installed_by_pin(
+    request: Request, platform_key: str, options: Options, pin: LockPin
+) -> Resolved | None:
+    return _lookup_by_pin(request, platform_key, options, pin)[0]
+
+
+def _lookup_by_pin(
+    request: Request, platform_key: str, options: Options, pin: LockPin
+) -> tuple[Resolved | None, bool]:
+    """The installed build a lock pin names, with no network: an unpacked
+    directory named by the pinned manifest digest, in the cache or a system
+    directory, whose `verified.json` is for this platform and records exactly
+    the pinned manifest, layer and bundle digests (public issues #414, #487).
+    `None` when no installed build matches; the flag is true when a record
+    exists under the pinned manifest but disagrees with the pin."""
+    roots = search_roots(options.cache_dir, options.system_dirs)
+    manifest_hex = parse_digest(pin.manifest)
+    mismatch = False
+    for root in roots:
+        udir = unpacked_dir_for(root, manifest_hex)
+        record = read_verified_record(udir)
+        if record is None:
+            continue
+        if (
+            record.platform == platform_key
+            and record.manifest == pin.manifest
+            and record.layer == pin.layer
+            and record.bundle == pin.bundle
+        ):
+            return (
+                _record_to_resolved(
+                    udir,
+                    record,
+                    request_spelling=request.spelling,
+                    already_installed=True,
+                    source=_source_for_dir(udir, roots),
+                ),
+                False,
+            )
+        mismatch = True
+    return None, mismatch
+
+
+def _resolve_frozen_offline(
+    request: Request, platform_key: str, options: Options, lock: Lock | None
+) -> Resolved:
+    """`--frozen --offline`: verify the installed build against the lock with
+    zero network. No lock entry for the request, or an installed record that
+    does not match the pin, is `CHTYPES_ARTIFACT_PINNED`; a pinned build that
+    is not installed is `CHTYPES_ARTIFACT_MISSING`."""
+    if lock is None:
+        raise ArtifactPinnedError("chtypes: --frozen requires a lock file; none was given")
+    pin = lock.pin_for(request.spelling, platform_key)
+    if pin is None:
+        raise ArtifactPinnedError(
+            f"chtypes: --frozen: no pin for {request.spelling!r} ({platform_key}) in the lock"
+        )
+    roots = search_roots(options.cache_dir, options.system_dirs)
+    warnings = probe_roots(roots, options.resolved_strict())
+    installed, mismatch = _lookup_by_pin(request, platform_key, options, pin)
+    if installed is None:
+        if mismatch:
+            raise ArtifactPinnedError(
+                f"chtypes: --frozen --offline: the installed build for {request.spelling} "
+                f"({platform_key}) does not match the lock's pin {pin.manifest}"
+            )
+        raise ArtifactMissingError(
+            with_notes(
+                f"chtypes: --frozen --offline: the build the lock pins ({pin.manifest}) "
+                f"is not installed for {request.spelling} ({platform_key})",
+                missing_notes(options),
+            )
+        )
+    return replace(installed, warnings=(*warnings, *installed.warnings))
+
+
 def _ensure_frozen(
     request: Request, platform_key: str, options: Options, lock: Lock | None
 ) -> Resolved:
@@ -916,17 +998,9 @@ def _ensure_frozen(
     cache_root_path = roots[0]
     scratch_root = _scratch_root(cache_root_path)
 
-    manifest_hex = parse_digest(pin.manifest)
-    existing_dir = unpacked_dir_for(cache_root_path, manifest_hex)
-    existing_record = read_verified_record(existing_dir)
-    if existing_record is not None and existing_record.platform == platform_key:
-        return _record_to_resolved(
-            existing_dir,
-            existing_record,
-            request_spelling=request.spelling,
-            already_installed=True,
-            source="cache",
-        )
+    installed = _installed_by_pin(request, platform_key, options, pin)
+    if installed is not None:
+        return installed
 
     manifest_doc, _raw = fetch_manifest_by_digest(bases, pin.manifest, policy=policy, retry=retry)
     layer_desc = manifest_layer_descriptor(manifest_doc)
@@ -1049,6 +1123,9 @@ def _ensure(
     request: Request, platform_key: str, options: Options, lock: Lock | None, roots: Sequence[Path]
 ) -> Resolved:
     try:
+        if options.resolved_offline() and options.frozen:
+            return _resolve_frozen_offline(request, platform_key, options, lock)
+
         if options.resolved_offline():
             resolved = resolve_installed(request, platform_key, options)
             if resolved is None:

chtypes/_ocifetch/_errors.py

@@ -47,17 +47,19 @@ __all__ = [
     "SourceUnreachableError",
 ]
 
-CODE_ARTIFACT_MISSING = "CHTYPES_ARTIFACT_MISSING"
-CODE_ARTIFACT_UNTRUSTED = "CHTYPES_ARTIFACT_UNTRUSTED"
-CODE_ARTIFACT_CORRUPT = "CHTYPES_ARTIFACT_CORRUPT"
-CODE_ARTIFACT_PINNED = "CHTYPES_ARTIFACT_PINNED"
-CODE_ARTIFACT_UNPUBLISHED = "CHTYPES_ARTIFACT_UNPUBLISHED"
-CODE_SOURCE_UNREACHABLE = "CHTYPES_SOURCE_UNREACHABLE"
-CODE_SOURCE_UNAUTHORIZED = "CHTYPES_SOURCE_UNAUTHORIZED"
-CODE_SOURCE_FORBIDDEN = "CHTYPES_SOURCE_FORBIDDEN"
-CODE_SOURCE_INCOMPATIBLE = "CHTYPES_SOURCE_INCOMPATIBLE"
-CODE_CACHE_UNUSABLE = "CHTYPES_CACHE_UNUSABLE"
-CODE_SOURCE_RETIRED = "CHTYPES_SOURCE_RETIRED"
+from chtypes._codes import (
+    CODE_ARTIFACT_CORRUPT,
+    CODE_ARTIFACT_MISSING,
+    CODE_ARTIFACT_PINNED,
+    CODE_ARTIFACT_UNPUBLISHED,
+    CODE_ARTIFACT_UNTRUSTED,
+    CODE_CACHE_UNUSABLE,
+    CODE_SOURCE_FORBIDDEN,
+    CODE_SOURCE_INCOMPATIBLE,
+    CODE_SOURCE_RETIRED,
+    CODE_SOURCE_UNAUTHORIZED,
+    CODE_SOURCE_UNREACHABLE,
+)
 
 _CODES_USED_HERE = (
     CODE_ARTIFACT_MISSING,

chtypes/_ocifetch/_hold.py

@@ -0,0 +1,133 @@
+"""The in-use signal (docs/guides/fetch-v1.md §1, "In use"; public issue #494).
+
+A process that is about to load an installed build, or that a registry's
+fetch handed one to, takes a SHARED advisory lock (flock) on the entry's
+`verified.json` and keeps it until the process exits. `chtypes prune` removes
+an entry only after it has taken the EXCLUSIVE lock without waiting, so it
+never removes a build a live process holds. The kernel drops a dead process's
+locks, so a crash never pins a build. flock belongs to the open file
+description on Linux and darwin, so a hold taken by this very process counts
+too, and so does one taken by any binding: all four lock the same file the
+same way.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import threading
+from collections.abc import Callable
+from pathlib import Path
+
+from chtypes._ocifetch import _constants as C
+from chtypes._ocifetch._errors import ArtifactMissingError
+
+try:
+    import fcntl
+except ImportError:  # not a platform chtypes serves: nothing is held, prune keeps everything
+    fcntl = None  # type: ignore[assignment]
+
+__all__ = [
+    "CLAIM_GONE",
+    "CLAIM_IN_USE",
+    "CLAIM_OWNED",
+    "HELD",
+    "UNHELD",
+    "VANISHED",
+    "claim",
+    "hold",
+    "removed_while_held",
+]
+
+# What `hold` found.
+HELD = "held"  # this process holds the entry, shared, for its life
+UNHELD = "unheld"  # the record cannot be locked here: go on (prune cannot lock it either)
+VANISHED = "vanished"  # the entry is gone or replaced: a prune removed it; look again
+
+# What `claim` found.
+CLAIM_OWNED = "owned"  # locked exclusively: no process holds it
+CLAIM_IN_USE = "in-use"  # a process holds it, or it cannot be locked: kept
+CLAIM_GONE = "gone"  # gone or replaced since it was listed: not ours to report
+
+_GONE = (errno.ENOENT, errno.ENOTDIR)
+
+# This process's shared locks: one open record per entry directory, kept until
+# the process exits.
+_holds_lock = threading.Lock()
+_holds: dict[str, int] = {}
+
+
+def _same_file(fd: int, path: str) -> bool:
+    try:
+        held = os.fstat(fd)
+        now = os.stat(path)
+    except OSError:
+        return False
+    return (held.st_dev, held.st_ino) == (now.st_dev, now.st_ino)
+
+
+def hold(entry_dir: str | os.PathLike[str]) -> str:
+    """Take this process's shared hold on the installed entry `entry_dir`
+    (`<root>/unpacked/sha256/<manifest hex>`) and keep it for the life of the
+    process. It waits only while a prune holds the entry exclusively, which a
+    prune does across one rename; then the entry is gone, and this says so."""
+    key = str(entry_dir)
+    record = os.path.join(key, C.CACHE_VERIFIED_RECORD)
+    with _holds_lock:
+        fd = _holds.get(key)
+        if fd is not None:
+            if _same_file(fd, record):
+                return HELD
+            # The entry this process held was removed and installed again: the
+            # old hold protects nothing now.
+            os.close(fd)
+            del _holds[key]
+        try:
+            fd = os.open(record, os.O_RDONLY)
+        except OSError as exc:
+            return VANISHED if exc.errno in _GONE else UNHELD
+        if fcntl is None:
+            os.close(fd)
+            return UNHELD
+        try:
+            fcntl.flock(fd, fcntl.LOCK_SH)  # retried on EINTR by Python itself (PEP 475)
+        except OSError:
+            os.close(fd)
+            return UNHELD
+        if not _same_file(fd, record):
+            os.close(fd)
+            return VANISHED
+        _holds[key] = fd
+        return HELD
+
+
+def claim(entry_dir: str | os.PathLike[str]) -> tuple[str, Callable[[], None] | None]:
+    """Take the exclusive lock a prune needs on `entry_dir`, without waiting.
+    It is owned only when no process holds the entry and the record it locked
+    is still the one at the path; the returned release drops the lock."""
+    record = os.path.join(str(entry_dir), C.CACHE_VERIFIED_RECORD)
+    try:
+        fd = os.open(record, os.O_RDONLY)
+    except OSError as exc:
+        return (CLAIM_GONE if exc.errno in _GONE else CLAIM_IN_USE), None
+    if fcntl is None:
+        os.close(fd)
+        return CLAIM_IN_USE, None
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        os.close(fd)
+        return CLAIM_IN_USE, None
+    if not _same_file(fd, record):
+        os.close(fd)
+        return CLAIM_GONE, None
+    return CLAIM_OWNED, lambda: os.close(fd)
+
+
+def removed_while_held(request: str, entry_dir: Path) -> ArtifactMissingError:
+    """`CHTYPES_ARTIFACT_MISSING` for a request whose build a concurrent prune
+    removed twice, each time between its install and this process's hold."""
+    return ArtifactMissingError(
+        f"chtypes: {entry_dir} was removed by a concurrent prune before this process "
+        f"could hold it; ask for {request} again"
+    )