pairing-core 0.4.1__py3-none-any.whl

pairing_core/__init__.py

@@ -0,0 +1,161 @@
+"""
+pairing-core — deterministic chess pairing library.
+
+Pairing systems: frozen ``dutch-till2026-compat`` Dutch kernel, the 2026
+family (``pairing_core.fide2026``: dutch/dubov/burstein/lim/double/team/
+olympiad + baku modifier), and Berger round robin. External engines
+(BBP, JaVaFo) are bring-your-own-binary adapters at
+``pairing_core.adapters`` (execution + TRF interchange; no provider
+integration, nothing bundled). No persistence, no network.
+
+Historical provenance: the frozen Dutch kernel was extracted
+behavior-preserving from 20kevit/chess-manager ``domain/pairing/``
+(v0.1.0 goldens pin it). Current capability authority:
+``docs/CAPABILITY.md``; conformance standing (explicit interpretations,
+no FIDE endorsement claimed):
+``docs/audit/FIDE_CONFORMANCE_MATRIX.md``.
+
+Public contract:
+    pair_canonical(...), CanonicalPlayer, CanonicalRequest,
+    pair(...), pair_detailed(...), pair_via(...), EngineRequest,
+    EngineProvider, Registry, RulesetId, ExecutionBudgets, CancelToken,
+    PlayerData, PairingCard, RoundResult, validate_round(...), ...
+
+Canonical engine abstraction:
+    PairingEngine.pair(request) -> RoundResult
+"""
+
+from pairing_core.models import PlayerData, PairingCard, RoundResult
+
+try:
+    from pairing_core.models import PlayerSnapshot
+except ImportError:  # pragma: no cover
+    PlayerSnapshot = PlayerData  # type: ignore
+
+from pairing_core.engine import pair_round, SwissEngine
+from pairing_core.validator import validate_round, ValidationReport, Finding
+from pairing_core.api import PairingRequest, PairingEngine, NativeDutchEngine
+from pairing_core.api import (
+    EngineRequest,
+    pair,
+    pair_detailed,
+    pair_via,
+    validate_request,
+    versions,
+)
+from pairing_core.errors import (
+    CancelledError,
+    DuplicatePlayerIdError,
+    EngineTimeoutError,
+    EngineUnavailableError,
+    ImpossiblePairingError,
+    InternalError,
+    InvalidPlayerError,
+    InvalidRequestError,
+    PairingError,
+    UnsupportedCapabilityError,
+    UnsupportedRulesetError,
+    VersionMismatchError,
+)
+from pairing_core.rulesets import (
+    DUTCH_TILL2026_COMPAT,
+    ConstraintSet,
+    RulesetId,
+    resolve_ruleset,
+)
+from pairing_core.envelope import Pairing, RoundPairing
+from pairing_core.controls import CancelToken, ExecutionBudgets
+from pairing_core.provider import (
+    Capability,
+    EngineMetadata,
+    EngineProvider,
+    NativeDutchProvider,
+)
+from pairing_core.registry import Registry, create_default_registry
+from pairing_core.roundrobin import round_robin
+from pairing_core.explain import (
+    BoardExplanation,
+    ByeExplanation,
+    Explanation,
+    explain,
+)
+from pairing_core.canonical import (
+    CANONICAL_REQUEST_SCHEMA,
+    KNOWN_SYSTEMS,
+    SYSTEM_DUTCH,
+    SYSTEM_ROUND_ROBIN,
+    CanonicalPlayer,
+    CanonicalRequest,
+    canonical_json,
+    describe_systems,
+    pair_canonical,
+)
+
+__version__ = "0.4.1"
+# Frozen-kernel reference marker (historical donor claim for the
+# pre-2026 Dutch formulation; kept byte-stable for consumers).
+# Current evidence posture: docs/CAPABILITY.md + conformance matrix.
+__fide_reference__ = "C.04.2 + C.04.3 (effective 1 July 2025)"
+
+__all__ = [
+    "PlayerData",
+    "PlayerSnapshot",
+    "PairingCard",
+    "RoundResult",
+    "PairingRequest",
+    "PairingEngine",
+    "NativeDutchEngine",
+    "SwissEngine",
+    "pair_round",
+    "validate_round",
+    "ValidationReport",
+    "Finding",
+    "EngineRequest",
+    "pair",
+    "pair_detailed",
+    "pair_via",
+    "validate_request",
+    "versions",
+    "RulesetId",
+    "ConstraintSet",
+    "resolve_ruleset",
+    "DUTCH_TILL2026_COMPAT",
+    "Pairing",
+    "RoundPairing",
+    "ExecutionBudgets",
+    "CancelToken",
+    "EngineProvider",
+    "NativeDutchProvider",
+    "Capability",
+    "EngineMetadata",
+    "Registry",
+    "create_default_registry",
+    "round_robin",
+    "explain",
+    "Explanation",
+    "BoardExplanation",
+    "ByeExplanation",
+    "CanonicalPlayer",
+    "CanonicalRequest",
+    "pair_canonical",
+    "canonical_json",
+    "describe_systems",
+    "CANONICAL_REQUEST_SCHEMA",
+    "KNOWN_SYSTEMS",
+    "SYSTEM_DUTCH",
+    "SYSTEM_ROUND_ROBIN",
+    "PairingError",
+    "InvalidRequestError",
+    "InvalidPlayerError",
+    "DuplicatePlayerIdError",
+    "ImpossiblePairingError",
+    "EngineTimeoutError",
+    "CancelledError",
+    "EngineUnavailableError",
+    "UnsupportedCapabilityError",
+    "UnsupportedRulesetError",
+    "VersionMismatchError",
+    "InternalError",
+    "__version__",
+    "__fide_reference__",
+]

pairing_core/adapters/__init__.py

@@ -0,0 +1,43 @@
+"""External-engine adapters (adapter edge, NOT core domain).
+
+Never imported by pairing-core core modules (import-lint enforced):
+TRF types, subprocess execution, and vendor-specific conventions live
+exclusively here. Adapters are bring-your-own-binary (O04/O06); absence of a
+binary is a typed failure, never a silent fallback.
+"""
+
+from pairing_core.adapters.trf import (
+    TournamentInput,
+    TrfPlayer,
+    TrfRound,
+    build_trf,
+    from_engine_request,
+    parse_pairing_output,
+    parse_trf,
+    validate_external_pairs,
+)
+from pairing_core.adapters import bbp, javafo, trf
+from pairing_core.adapters.bbp import (
+    BBPConfig,
+    BBPPairing,
+    pair_tournament,
+    probe_version,
+)
+
+__all__ = [
+    "bbp",
+    "javafo",
+    "trf",
+    "TournamentInput",
+    "TrfPlayer",
+    "TrfRound",
+    "build_trf",
+    "from_engine_request",
+    "parse_pairing_output",
+    "parse_trf",
+    "validate_external_pairs",
+    "BBPConfig",
+    "BBPPairing",
+    "pair_tournament",
+    "probe_version",
+]

pairing_core/adapters/_process.py

@@ -0,0 +1,210 @@
+"""Supervised subprocess execution for engine adapters (INTERNAL).
+
+Not exported from pairing_core.adapters. Rules (SECURITY.md posture,
+blueprint H, O10):
+
+- argv lists only, never shell strings (no shell=True, no unsanitized
+  interpolation). Timeouts kill after a grace period and reap (no zombies).
+- Bounded stdout/stderr capture (10 MiB each; beyond -> InternalError, not
+  memory exhaustion). The bound is enforced DURING collection by reader
+  threads that kill the child as soon as either stream exceeds the cap, so
+  a hostile executable cannot grow parent memory by writing unlimited
+  output. Strict UTF-8 decode; undecodable bytes -> InternalError.
+- Args, executable path, and working directory are caller-supplied and
+  explicit (BYO binaries). No PATH searching, no downloading, no guessing.
+- Returns CompletedRun; interpretation (exit-code mapping) belongs to the
+  per-engine adapter, which has the authoritative manual.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from typing import BinaryIO, List, Optional, Sequence
+
+from pairing_core.errors import EngineTimeoutError, InternalError
+
+OUTPUT_CAP = 10 * 1024 * 1024
+KILL_GRACE_SECONDS = 5.0
+_READ_CHUNK = 65536
+_POLL_INTERVAL_SECONDS = 0.05
+
+
+@dataclass(frozen=True)
+class CompletedRun:
+    """INTERNAL. Captured outcome of one supervised execution."""
+    argv: tuple
+    returncode: int
+    stdout: str
+    stderr: str
+    elapsed_seconds: float
+    timed_out: bool
+
+
+def _pump_pipe(stream: BinaryIO, buf: bytearray, lock: threading.Lock,
+               over: List[bool], over_event: threading.Event) -> None:
+    """INTERNAL. Drain one child pipe in chunks, enforcing OUTPUT_CAP.
+
+    Runs on a daemon reader thread so both pipes drain concurrently (no
+    deadlock when the child fills one pipe while writing the other).
+    Sets over/over_event the moment this stream exceeds the cap; the
+    main thread then kills the child. Parent memory per stream never
+    exceeds OUTPUT_CAP + one chunk, regardless of child output volume.
+    A closed/torn-down pipe reads as EOF (ValueError/OSError tolerated).
+    """
+    try:
+        while True:
+            chunk = stream.read(_READ_CHUNK)
+            if not chunk:
+                return
+            with lock:
+                buf += chunk
+                if len(buf) > OUTPUT_CAP and not over[0]:
+                    over[0] = True
+                    over_event.set()
+                    return
+    except (OSError, ValueError):
+        return
+
+
+def _finish_readers(proc: subprocess.Popen,
+                    readers: List[threading.Thread]) -> None:
+    """INTERNAL. Bounded drain of reader threads, then close pipe fds.
+
+    Readers normally finish on child EOF. If a thread is still blocked
+    (e.g. a grandchild inherited the pipe), closing the fds unblocks it:
+    the pump treats the resulting ValueError as EOF. Threads are daemon,
+    so nothing here can hang interpreter shutdown.
+    """
+    for thread in readers:
+        thread.join(timeout=KILL_GRACE_SECONDS)
+    for pipe in (proc.stdout, proc.stderr):
+        try:
+            if pipe is not None:
+                pipe.close()
+        except (OSError, ValueError):
+            pass
+    for thread in readers:
+        thread.join(timeout=KILL_GRACE_SECONDS)
+
+
+def _kill_quietly(proc: subprocess.Popen) -> None:
+    """INTERNAL. SIGKILL that tolerates an already-exited child."""
+    try:
+        proc.kill()
+    except OSError:
+        pass
+
+
+def run_command(argv: Sequence[str], *, timeout_seconds: float,
+                workdir: Optional[str] = None) -> CompletedRun:
+    """Run argv (no shell) with timeout; kill-after-grace; bounded capture.
+
+    Timeout -> EngineTimeoutError (after terminating + reaping the child).
+    Either stream exceeding 10 MiB -> InternalError, raised promptly while
+    the child is still producing output (the child is killed first).
+    Spawn failures (missing/unexecutable) -> InternalError here; adapters
+    pre-check paths and raise EngineUnavailableError with better context.
+    """
+    if timeout_seconds is None or not timeout_seconds > 0:
+        raise InternalError("run_command requires timeout_seconds > 0.")
+    start = time.monotonic()
+    try:
+        proc = subprocess.Popen(
+            list(argv), stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            cwd=workdir, shell=False)
+    except (OSError, ValueError) as exc:
+        raise InternalError(f"cannot spawn {argv[0]!r}: {exc}") from exc
+    out_buf = bytearray()
+    err_buf = bytearray()
+    lock = threading.Lock()
+    over = [False]
+    over_event = threading.Event()
+    readers = [
+        threading.Thread(target=_pump_pipe,
+                         args=(proc.stdout, out_buf, lock, over, over_event),
+                         name="pairing-core-stdout-pump", daemon=True),
+        threading.Thread(target=_pump_pipe,
+                         args=(proc.stderr, err_buf, lock, over, over_event),
+                         name="pairing-core-stderr-pump", daemon=True),
+    ]
+    for thread in readers:
+        thread.start()
+    try:
+        deadline = start + timeout_seconds
+        timed_out = False
+        while True:
+            if over_event.is_set():
+                _kill_quietly(proc)  # no-op if the child already exited
+                break
+            if proc.poll() is not None:
+                break
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                timed_out = True
+                _kill_quietly(proc)
+                break
+            over_event.wait(timeout=min(_POLL_INTERVAL_SECONDS, remaining))
+        if timed_out:
+            _finish_readers(proc, readers)
+            elapsed = time.monotonic() - start
+            raise EngineTimeoutError(
+                f"engine exceeded {timeout_seconds}s wall-clock budget "
+                f"(killed after {elapsed:.1f}s).") from None
+        if over_event.is_set():
+            _finish_readers(proc, readers)
+            raise InternalError(
+                "engine output exceeded 10 MiB capture cap.")
+        # Normal exit: bounded drain of already-buffered pipe data.
+        _finish_readers(proc, readers)
+        out = bytes(out_buf)
+        err = bytes(err_buf)
+    finally:
+        # Absolute cleanup on every path: no zombies, no leaked fds.
+        try:
+            if proc.poll() is None:
+                proc.kill()
+        except OSError:
+            pass
+        try:
+            proc.wait(timeout=KILL_GRACE_SECONDS)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            proc.wait()
+        for pipe in (proc.stdout, proc.stderr):
+            try:
+                if pipe is not None:
+                    pipe.close()
+            except (OSError, ValueError):
+                pass
+    elapsed = time.monotonic() - start
+    try:
+        stdout = out.decode("utf-8")
+        stderr = err.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise InternalError(
+            f"engine output is not UTF-8: {exc}") from exc
+    return CompletedRun(argv=tuple(argv), returncode=proc.returncode,
+                        stdout=stdout, stderr=stderr,
+                        elapsed_seconds=elapsed, timed_out=False)
+
+
+def check_executable(path: str, what: str) -> str:
+    """INTERNAL. Validate an explicit binary path (exists + executable)."""
+    from pairing_core.errors import EngineUnavailableError
+
+    if not isinstance(path, str) or not path:
+        raise EngineUnavailableError(f"{what}: explicit path required.")
+    if not os.path.isfile(path) or not os.access(path, os.X_OK):
+        raise EngineUnavailableError(
+            f"{what}: not an executable file: {path!r}.")
+    return path
+
+
+def temp_workdir() -> tempfile.TemporaryDirectory:
+    """INTERNAL. Scratch dir for one adapter run (caller cleans up)."""
+    return tempfile.TemporaryDirectory(prefix="pairing-core-")

pairing_core/adapters/bbp.py

@@ -0,0 +1,179 @@
+"""BBP external reference adapter (W3 foundation).
+
+Bring-your-own-binary; never bundled, never auto-discovered (O04/O06).
+No BBP structures leak into core: conversion happens here, at the adapter
+boundary, via the TRF subset (adapters/trf.py). No EngineProvider is shipped
+yet — provider integration waits until request histories can carry
+per-round data (later phase); this module is the execution + conversion
+layer the harness and a future provider will share.
+
+Authoritative behavior source: BBP README (primary, retrieved in full —
+CLI ``--dutch/--burstein -p/-c/-g/-r/-s``, TRF-2026 + TRF(bx), exit codes
+0-5, checklist + RTG, Apache-2.0). Only the Dutch pairing path is wrapped;
+Burstein is self-declared flawed upstream and NOT wrapped (refusing, not
+misrepresenting).
+
+Exit-code mapping (per BBP manual):
+  0 ok | 1 no valid pairing -> ImpossiblePairingError
+  2 unexpected -> InternalError | 3 invalid request -> InvalidRequestError
+  4 unhandleable size -> InternalError (resource exhaustion, captured)
+  5 file access -> EngineUnavailableError | other -> InternalError.
+Timeout (ours, wall-clock) -> EngineTimeoutError with termination.
+Missing/unexecutable binary or failed version probe -> EngineUnavailableError.
+Malformed pairing output -> InternalError with captured excerpt.
+
+Live-binary verification is PENDING (no binary in this environment); the
+execution path is tested against fixture stub executables.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import List, Optional, Tuple
+
+from pairing_core.adapters._process import (
+    CompletedRun,
+    check_executable,
+    run_command,
+    temp_workdir,
+)
+from pairing_core.adapters.trf import (
+    TournamentInput,
+    build_trf,
+    parse_pairing_output,
+    validate_external_pairs,
+)
+from pairing_core.errors import (
+    EngineTimeoutError,
+    EngineUnavailableError,
+    ImpossiblePairingError,
+    InternalError,
+    InvalidRequestError,
+)
+
+BBP_SYSTEM_DUTCH = "--dutch"
+EXIT_DESCRIPTIONS = {
+    1: "no valid pairing exists for the current round",
+    2: "unexpected engine error",
+    3: "invalid request (e.g. malformed input file)",
+    4: "unhandleable data size / out of memory",
+    5: "file access error",
+}
+
+
+@dataclass(frozen=True)
+class BBPConfig:
+    """PUBLIC. Explicit BYO-binary configuration (no discovery)."""
+    executable: str
+    timeout_seconds: float = 60.0
+    system: str = BBP_SYSTEM_DUTCH
+
+    def __post_init__(self) -> None:
+        if self.system != BBP_SYSTEM_DUTCH:
+            raise InvalidRequestError(
+                "only --dutch is wrapped (Burstein upstream is "
+                "self-declared flawed; refusing to wrap it).")
+        if not isinstance(self.timeout_seconds, (int, float)) or \
+                isinstance(self.timeout_seconds, bool) or \
+                not self.timeout_seconds > 0:
+            raise InvalidRequestError("timeout_seconds must be a number > 0.")
+
+
+@dataclass(frozen=True)
+class BBPPairing:
+    """PUBLIC. Captured outcome of one BBP Dutch pairing run."""
+    pairs: Tuple[Tuple[int, Optional[int]], ...]
+    engine_version: str
+    elapsed_seconds: float
+    command: Tuple[str, ...] = ()
+    stdout: str = ""
+    stderr: str = ""
+
+
+def probe_version(executable: str,
+                  timeout_seconds: float = 30.0) -> str:
+    """Run `<exe> -r`; return the release/build line.
+
+    Failure (any) -> EngineUnavailableError: version identity is required
+    for reproducibility metadata, never guessed.
+    """
+    exe = check_executable(executable, "BBP executable")
+    try:
+        run = run_command([exe, "-r"], timeout_seconds=timeout_seconds)
+    except (InternalError, EngineTimeoutError) as exc:
+        raise EngineUnavailableError(
+            f"BBP version probe failed for {exe!r}: {exc}") from exc
+    first = run.stdout.strip().splitlines()
+    if run.returncode != 0 or not first:
+        raise EngineUnavailableError(
+            f"BBP version probe failed for {exe!r}: exit "
+            f"{run.returncode}, stderr={run.stderr[:500]!r}.")
+    return first[0].strip()
+
+
+def pair_tournament(config: BBPConfig,
+                    tournament: TournamentInput) -> BBPPairing:
+    """Run BBP Dutch pairing over a TRF input; return captured pairs.
+
+    Raises per the exit-code mapping above. stdout/stderr/command/version
+    are captured for harness diagnostics and reproducibility.
+    """
+    exe = check_executable(config.executable, "BBP executable")
+    version = probe_version(exe)
+    text = build_trf(tournament)
+    with temp_workdir() as workdir:
+        src = os.path.join(workdir, "input.trf")
+        out = os.path.join(workdir, "output.txt")
+        try:
+            with open(src, "w", encoding="utf-8") as fh:
+                fh.write(text)
+        except OSError as exc:
+            raise InternalError(
+                f"cannot write BBP input file: {exc}") from exc
+        argv = [exe, config.system, src, "-p", out]
+        try:
+            run = run_command(argv, timeout_seconds=config.timeout_seconds,
+                              workdir=workdir)
+        except EngineTimeoutError:
+            raise
+        _check_exit(run, exe)
+        pairs = _read_output(out, exe)
+        validate_external_pairs(
+            pairs,
+            tuple(p.pairing_id for p in tournament.players),
+            absent_ids=tuple(tournament.absent_ids),
+            engine=f"BBP {exe!r}")
+    return BBPPairing(pairs=tuple(pairs), engine_version=version,
+                      elapsed_seconds=run.elapsed_seconds,
+                      command=tuple(argv), stdout=run.stdout,
+                      stderr=run.stderr)
+
+
+def _check_exit(run: CompletedRun, exe: str) -> None:
+    code = run.returncode
+    if code == 0:
+        return
+    detail = EXIT_DESCRIPTIONS.get(code, f"unknown exit code {code}")
+    context = f"BBP {exe!r} exit {code} ({detail}); stderr={run.stderr[:500]!r}."
+    if code == 1:
+        raise ImpossiblePairingError(context)
+    if code == 3:
+        raise InvalidRequestError(context)
+    if code == 5:
+        raise EngineUnavailableError(context)
+    raise InternalError(context)
+
+
+def _read_output(path: str, exe: str) -> List[Tuple[int, Optional[int]]]:
+    try:
+        with open(path, encoding="utf-8") as fh:
+            text = fh.read()
+    except OSError as exc:
+        raise InternalError(
+            f"BBP {exe!r} produced no readable output file: {exc}") from exc
+    try:
+        return parse_pairing_output(text)
+    except InternalError as exc:
+        raise InternalError(f"BBP {exe!r} malformed pairing output: "
+                            f"{exc}") from exc