nab-resolver 0.0.1__py3-none-any.whl

nab_resolver/__init__.py

@@ -0,0 +1 @@
+"""PubGrub dependency resolver."""

nab_resolver/conflict.py

@@ -0,0 +1,491 @@
+"""Conflict resolution and backtracking for the PubGrub resolver.
+
+Owns the conflict-resolution loop, the most-recent-satisfier
+search, the always-learn force-resolution gate, the targeted
+backtrack queue, and the catastrophic restart handler.
+
+Reference: https://github.com/dart-lang/pub/blob/master/doc/solver.md#conflict-resolution
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .errors import ResolutionError
+from .incompat_index import add_incompatibility
+from .partial_solution import PartialSolution
+from .report import format_error, prior_cause
+from .root import ROOT
+from .types import Incompatibility, IncompatibilityCause
+
+if TYPE_CHECKING:
+    from .partial_solution import Assignment
+    from .resolver import Resolver
+    from .types import Term
+
+
+__all__ = [
+    "apply_targeted_backtrack",
+    "conflict_resolution",
+    "find_most_recent_satisfier",
+    "force_targeted_backtrack",
+    "is_terminal_incompatibility",
+    "iterate_force_resolution",
+    "maybe_restart",
+    "maybe_targeted_backtrack",
+    "recompute_previous_level",
+    "try_force_resolution_step",
+    "update_culprit_counts",
+]
+
+
+# Soundness gate for try_force_resolution_step: a single-term
+# incompatibility must resolve to >= 2 terms to keep the eliminated
+# package's conditioning.
+_SINGLE_TERM = 1
+_MIN_RESOLVED_TERMS = 2
+
+# Lowest decision level a targeted-backtrack can land above without
+# removing ROOT (decided at level 1 in _add_root_requirements).
+_TARGETED_BT_MIN_LEVEL = 2
+
+
+def conflict_resolution(
+    resolver: Resolver[Any, Any],
+    conflicting_incompatibility: Incompatibility[Any, Any],
+) -> Incompatibility[Any, Any]:
+    """Learn a new incompatibility and backjump to the appropriate level.
+
+    Implements PubGrub's conflict resolution algorithm: resolve
+    backwards through the assignment trail combining incompatibilities
+    until the learned clause has at most one term at the current
+    decision level.
+
+    Reference: https://github.com/dart-lang/pub/blob/master/doc/solver.md#conflict-resolution
+    """
+    current_incompatibility = conflicting_incompatibility
+    is_derived = False
+
+    while True:
+        if is_terminal_incompatibility(current_incompatibility):
+            # Unreachable in practice: the backjump_target == 0 check below
+            # preempts this path.  Kept as a safety net.
+            raise ResolutionError(  # pragma: no cover
+                format_error(current_incompatibility),
+                incompatibility=current_incompatibility,
+            )
+
+        satisfier_result = find_most_recent_satisfier(resolver, current_incompatibility)
+        most_recent_satisfier = satisfier_result[0]
+        most_recent_satisfier_term = satisfier_result[1]
+        previous_satisfier_level = satisfier_result[2]
+
+        can_backjump = (
+            most_recent_satisfier.is_decision
+            or previous_satisfier_level != most_recent_satisfier.decision_level
+        )
+
+        if can_backjump:
+            (
+                current_incompatibility,
+                most_recent_satisfier,
+                most_recent_satisfier_term,
+                previous_satisfier_level,
+                forced_any,
+            ) = iterate_force_resolution(
+                resolver,
+                current_incompatibility,
+                most_recent_satisfier,
+                most_recent_satisfier_term,
+                previous_satisfier_level,
+            )
+            if forced_any:
+                is_derived = True
+
+        resolver.observer.on_conflict_step(
+            current_incompatibility,
+            satisfier_package=most_recent_satisfier.package,
+            satisfier_is_decision=most_recent_satisfier.is_decision,
+            satisfier_level=most_recent_satisfier.decision_level,
+            previous_level=previous_satisfier_level,
+            can_backjump=can_backjump,
+        )
+
+        if can_backjump:
+            if is_derived:
+                add_incompatibility(resolver, current_incompatibility)
+                resolver.stats.incompatibilities_learned += 1
+                resolver.observer.on_learned(current_incompatibility)
+
+            backjump_target = previous_satisfier_level
+            if (
+                most_recent_satisfier.is_decision
+                and backjump_target >= most_recent_satisfier.decision_level
+            ):
+                backjump_target = most_recent_satisfier.decision_level - 1
+
+            backjump_target = min(backjump_target, resolver.solution.decision_level)
+            backjump_target = max(backjump_target, 0)
+
+            if backjump_target == 0:
+                raise ResolutionError(
+                    format_error(current_incompatibility),
+                    incompatibility=current_incompatibility,
+                )
+
+            from_level = resolver.solution.decision_level
+            resolver.solution.backtrack(backjump_target)
+            resolver.stats.backjumps += 1
+            resolver.observer.on_backjump(from_level, backjump_target)
+
+            # Count only the "affected" package so it gets decided first
+            # after restart and its dependencies constrain the culprit.
+            affected_package = most_recent_satisfier.package
+            resolver.stats.package_conflict_counts[affected_package] += 1
+
+            update_culprit_counts(
+                resolver,
+                current_incompatibility,
+                affected_package,
+                most_recent_satisfier,
+            )
+
+            return current_incompatibility
+
+        # Can't backjump yet: resolve with the satisfier's cause.
+        assert most_recent_satisfier.cause is not None
+        assert most_recent_satisfier_term is not None
+        is_derived = True
+
+        resolved_terms = prior_cause(
+            current_incompatibility,
+            most_recent_satisfier.cause,
+            most_recent_satisfier_term.package,
+        )
+
+        current_incompatibility = Incompatibility(
+            resolved_terms,
+            cause=IncompatibilityCause.DERIVED,
+            cause_left=current_incompatibility,
+            cause_right=most_recent_satisfier.cause,
+        )
+
+
+def update_culprit_counts(
+    resolver: Resolver[Any, Any],
+    incompatibility: Incompatibility[Any, Any],
+    affected_package: Any,
+    satisfier: Assignment[Any, Any],
+) -> None:
+    """Credit non-affected packages in a learned clause as culprits.
+
+    Modelled on uv's ConflictTracker (PR #9843).  Every non-affected,
+    non-root package in the clause is a culprit; for single-term NO_VERSIONS
+    clauses we walk the satisfier's cause chain instead.  When a culprit
+    crosses ``CULPRIT_THRESHOLD`` it gets queued for targeted backtrack.
+    """
+    culprit_packages: set[Any] = set()
+    for term in incompatibility.terms:
+        package = term.package
+        if package is ROOT or package == affected_package:
+            continue
+        culprit_packages.add(package)
+
+    # Single-term NO_VERSIONS clauses carry the antecedent decisions only
+    # via the satisfier's cause; without this, those decisions go uncredited.
+    if len(incompatibility.terms) == 1 and satisfier.cause is not None:
+        for term in satisfier.cause.terms:
+            package = term.package
+            if package is ROOT or package == affected_package:
+                continue
+            culprit_packages.add(package)
+
+    threshold = resolver.CULPRIT_THRESHOLD
+    for package in culprit_packages:
+        resolver.stats.package_culprit_counts[package] += 1
+        count = resolver.stats.package_culprit_counts[package]
+        if (
+            count >= threshold
+            and count % threshold == 0
+            and package not in resolver.pending_targeted_backtrack
+        ):
+            resolver.pending_targeted_backtrack.append(package)
+
+
+def iterate_force_resolution(
+    resolver: Resolver[Any, Any],
+    incompatibility: Incompatibility[Any, Any],
+    satisfier: Assignment[Any, Any],
+    satisfier_term: Term[Any, Any],
+    previous_satisfier_level: int,
+) -> tuple[
+    Incompatibility[Any, Any],
+    Assignment[Any, Any],
+    Term[Any, Any],
+    int,
+    bool,
+]:
+    """Iterate :func:`try_force_resolution_step` while it succeeds.
+
+    Returns the (possibly-resolved) incompatibility, refreshed satisfier,
+    satisfier term, previous-satisfier level, and a ``forced_any`` flag
+    indicating whether at least one resolution step happened.  Stops when
+    ``try_force_resolution_step`` declines (returns ``None``).
+    """
+    forced_any = False
+
+    while True:
+        forced = try_force_resolution_step(
+            resolver, incompatibility, satisfier, satisfier_term
+        )
+        if forced is None:
+            break
+        forced_any = True
+        incompatibility = forced
+        (
+            satisfier,
+            satisfier_term,
+            previous_satisfier_level,
+        ) = find_most_recent_satisfier(resolver, forced)
+
+    return (
+        incompatibility,
+        satisfier,
+        satisfier_term,
+        previous_satisfier_level,
+        forced_any,
+    )
+
+
+def try_force_resolution_step(
+    resolver: Resolver[Any, Any],
+    incompatibility: Incompatibility[Any, Any],
+    satisfier: Assignment[Any, Any],
+    satisfier_term: Term[Any, Any],
+) -> Incompatibility[Any, Any] | None:
+    """Resolve a single-term NO_VERSIONS clause once with a soundness gate.
+
+    Standard PubGrub backjumps to root for single-term clauses, losing the
+    supporting decisions; resolving once with the satisfier's cause exposes
+    them so later propagation can skip the bad decision.
+
+    Returns ``None`` when the resolved clause collapses to <2 terms (the
+    eliminated package's conditioning would be lost) or when it is not
+    assert-eligible.
+    """
+    if (
+        satisfier.is_decision
+        or len(incompatibility.terms) != _SINGLE_TERM
+        or satisfier.cause is None
+    ):
+        return None
+
+    resolved_terms = prior_cause(
+        incompatibility, satisfier.cause, satisfier_term.package
+    )
+    if len(resolved_terms) < _MIN_RESOLVED_TERMS:
+        return None
+
+    forced = Incompatibility(
+        resolved_terms,
+        cause=IncompatibilityCause.DERIVED,
+        cause_left=incompatibility,
+        cause_right=satisfier.cause,
+    )
+
+    forced_recent, _, forced_prev_level = find_most_recent_satisfier(resolver, forced)
+    forced_can_backjump = (
+        forced_recent.is_decision or forced_prev_level != forced_recent.decision_level
+    )
+    if not forced_can_backjump:
+        return None
+
+    return forced
+
+
+def find_most_recent_satisfier(
+    resolver: Resolver[Any, Any], incompatibility: Incompatibility[Any, Any]
+) -> tuple[Assignment[Any, Any], Term[Any, Any], int]:
+    """Find the most recently assigned satisfier across all terms.
+
+    Returns ``(satisfier, term, previous_satisfier_level)``.  The previous
+    level is the highest among the other terms' satisfiers and bounds how
+    far back the resolver can jump.  Refined when the satisfier is partial
+    (earlier assignments also contributed).
+    """
+    most_recent: Assignment[Any, Any] | None = None
+    most_recent_term: Term[Any, Any] | None = None
+    previous_level = 1  # root's level
+
+    for term in incompatibility.terms:
+        satisfier = resolver.solution.satisfier(term)
+        if satisfier is None:  # pragma: no cover
+            unreachable = (
+                f"Bug: no satisfier for {term!r} in a satisfied incompatibility"
+            )
+            raise RuntimeError(unreachable)
+        satisfier_index = satisfier.trail_index
+        if most_recent is None or (satisfier_index > most_recent.trail_index):
+            if most_recent is not None:
+                previous_level = max(previous_level, most_recent.decision_level)
+            most_recent = satisfier
+            most_recent_term = term
+        else:
+            previous_level = max(previous_level, satisfier.decision_level)
+
+    if most_recent is None:  # pragma: no cover
+        unreachable = "Bug: no satisfiers in a satisfied incompatibility"
+        raise RuntimeError(unreachable)
+    assert most_recent_term is not None
+
+    if not resolver.solution.satisfier_is_sole(most_recent, most_recent_term):
+        previous_level = recompute_previous_level(
+            resolver, most_recent, most_recent_term, previous_level
+        )
+
+    return most_recent, most_recent_term, previous_level
+
+
+def recompute_previous_level(
+    resolver: Resolver[Any, Any],
+    satisfier: Assignment[Any, Any],
+    satisfier_term: Term[Any, Any],
+    current_previous_level: int,
+) -> int:
+    """Refine previous_level when the satisfier is partial.
+
+    Isolates the satisfier's own contribution (from its cause), subtracts
+    it from the term, and folds the remainder's satisfier level in.
+    """
+    if satisfier.cause is None:
+        return current_previous_level
+
+    cause_term = None
+    for term in satisfier.cause.terms:
+        if term.package == satisfier_term.package:
+            cause_term = term
+            break
+    if cause_term is None:
+        return current_previous_level
+
+    individual = cause_term.negate()
+    remainder = satisfier_term.intersect(individual.negate())
+    if remainder is None or remainder.constraint.is_empty:
+        return current_previous_level
+
+    remainder_satisfier = resolver.solution.satisfier(remainder)
+    if remainder_satisfier is not None:
+        return max(current_previous_level, remainder_satisfier.decision_level)
+    return current_previous_level
+
+
+def is_terminal_incompatibility(incompatibility: Incompatibility[Any, Any]) -> bool:
+    """Check whether this incompatibility proves resolution is impossible."""
+    if not incompatibility.terms:
+        return True
+    return all(term.package is ROOT for term in incompatibility.terms)
+
+
+def maybe_targeted_backtrack(resolver: Resolver[Any, Any]) -> Any | None:
+    """Run :func:`apply_targeted_backtrack` if the gate is open.
+
+    Gate: pending non-empty AND total conflicts past
+    ``TARGETED_BT_MIN_CONFLICTS``.  Pending culprits are kept across rounds.
+    """
+    if (
+        resolver.pending_targeted_backtrack
+        and resolver.stats.conflicts >= resolver.TARGETED_BT_MIN_CONFLICTS
+    ):
+        return apply_targeted_backtrack(resolver)
+    return None
+
+
+def maybe_restart(
+    resolver: Resolver[Any, Any],
+    restart_threshold: int,
+    restarts_remaining: int,
+) -> tuple[int, int, bool]:
+    """Restart the solver if any package crossed ``restart_threshold``.
+
+    Returns ``(new_threshold, new_remaining, restarted)``.  Preserves
+    ``incompatibilities`` and ``package_conflict_counts`` across restart.
+    """
+    if restarts_remaining <= 0:
+        return restart_threshold, restarts_remaining, False
+
+    max_count = max(resolver.stats.package_conflict_counts.values(), default=0)
+    if max_count < restart_threshold:
+        return restart_threshold, restarts_remaining, False
+
+    resolver.stats.restarts += 1
+    resolver.solution = PartialSolution(range_type=resolver.range_type)
+    resolver.solution.decide(ROOT, resolver.root_version)
+    resolver.pending_targeted_backtrack.clear()
+    resolver.stats.targeted_backtracks = 0
+
+    return restart_threshold * 2, restarts_remaining - 1, True
+
+
+def force_targeted_backtrack(
+    resolver: Resolver[Any, Any], packages: list[Any]
+) -> Any | None:
+    """Apply a targeted back-track without waiting for the normal gate.
+
+    Used when the provider supplies direct evidence that the named
+    packages are culprits. Bumps each package's culprit count past the
+    dominant-culprit threshold, queues it, and applies immediately.
+
+    Returns the back-jumped package, or ``None`` if the back-track did
+    not move the decision level.
+    """
+    if not packages:
+        return None
+
+    threshold = resolver.CULPRIT_THRESHOLD
+    for package in packages:
+        current = resolver.stats.package_culprit_counts[package]
+        if current < threshold:
+            resolver.stats.package_culprit_counts[package] = threshold
+        if package not in resolver.pending_targeted_backtrack:
+            resolver.pending_targeted_backtrack.append(package)
+
+    return apply_targeted_backtrack(resolver)
+
+
+def apply_targeted_backtrack(resolver: Resolver[Any, Any]) -> Any | None:
+    """Backtrack to before the earliest pending-culprit assignment.
+
+    Picks the smallest decision-level among queued culprits' first assignments
+    (decision OR derivation; derivations count too so propagated culprits in
+    cluster conflicts still trigger a backtrack) and jumps to one before it.
+    Capped at ``MAX_TARGETED_BACKTRACKS`` per restart segment.
+
+    Level-1 assignments are skipped to preserve ROOT.
+    """
+    if resolver.stats.targeted_backtracks >= resolver.MAX_TARGETED_BACKTRACKS:
+        resolver.pending_targeted_backtrack.clear()
+        return None
+
+    target_level = resolver.solution.decision_level
+    triggering_package: Any | None = None
+
+    for package in resolver.pending_targeted_backtrack:
+        package_entries = resolver.solution.assignments_for(package)
+        # Use the package's earliest non-level-1 assignment: jumping
+        # further than that would just undo unrelated work.
+        for assignment in package_entries:
+            if assignment.decision_level < _TARGETED_BT_MIN_LEVEL:
+                continue
+            candidate = assignment.decision_level - 1
+            if candidate < target_level:
+                target_level = candidate
+                triggering_package = package
+            break
+
+    resolver.pending_targeted_backtrack.clear()
+    if triggering_package is None or target_level >= resolver.solution.decision_level:
+        return None
+
+    resolver.solution.backtrack(target_level)
+    resolver.stats.targeted_backtracks += 1
+    return triggering_package

nab_resolver/decide.py

@@ -0,0 +1,138 @@
+"""Decision making for the PubGrub resolver.
+
+Picks the next undecided package, asks the provider for a version,
+and records ``NO_VERSIONS`` clauses or constraint clauses as needed.
+
+Reference: https://github.com/dart-lang/pub/blob/master/doc/solver.md#decision-making
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .incompat_index import add_incompatibility
+from .root import ROOT
+from .types import Incompatibility, IncompatibilityCause, Term
+
+if TYPE_CHECKING:
+    from .resolver import Resolver
+
+__all__ = [
+    "absorb_pending_clauses",
+    "choose_package_to_decide",
+    "choose_version",
+    "inject_constraint",
+    "record_no_versions",
+]
+
+
+def choose_package_to_decide(resolver: Resolver[Any, Any]) -> Any | None:
+    """Choose the next undecided package, or None if all decided.
+
+    Prefers ``is_ready`` packages so resolution keeps making progress while
+    other listings/metadata are still in flight.
+    """
+    undecided = resolver.solution.undecided_packages()
+    undecided.discard(ROOT)
+    if not undecided:
+        return None
+
+    conflict_counts = resolver.stats.package_conflict_counts
+    culprit_counts = resolver.stats.package_culprit_counts
+    get_range = resolver.solution.get
+    any_range = resolver.range_type.full()
+    prioritize = resolver.provider.prioritize
+    is_ready = resolver.provider.is_ready
+    tiebreak_cache = resolver.tiebreak_cache
+    root_order = resolver.root_package_order
+
+    def sort_key(package: Any) -> tuple[Any, ...]:
+        priority = prioritize(
+            package,
+            get_range(package) or any_range,
+            conflict_counts,
+            culprit_counts,
+        )
+        ready_penalty = 0 if is_ready(package) else 1
+        tiebreak = tiebreak_cache.get(package)
+        if tiebreak is None:
+            tiebreak = root_order.get(package)
+            if tiebreak is None:
+                tiebreak = (1, 0, str(package))
+            tiebreak_cache[package] = tiebreak
+        return (ready_penalty, priority, tiebreak)
+
+    return min(undecided, key=sort_key)
+
+
+def inject_constraint(resolver: Resolver[Any, Any], package: Any) -> bool:
+    """Inject a CONSTRAINT incompatibility for a package, if applicable.
+
+    Lazy: only fires the first time the package is about to be decided.
+    Returns True if an incompatibility was injected (caller re-propagates).
+    """
+    if package not in resolver.constraints:
+        return False
+    if package in resolver.injected_constraints:
+        return False
+
+    resolver.injected_constraints.add(package)
+    complement = ~resolver.constraints[package]
+    if complement.is_empty:
+        return False
+
+    add_incompatibility(
+        resolver,
+        Incompatibility(
+            [Term(package, complement, positive=True)],
+            cause=IncompatibilityCause.CONSTRAINT,
+        ),
+    )
+    return True
+
+
+def choose_version(resolver: Resolver[Any, Any], package: Any) -> Any | None:
+    """Ask the provider to pick a version within the allowed range."""
+    current_range = resolver.solution.get(package) or resolver.range_type.full()
+    resolver.provider.receive_partial_solution_hint(
+        resolver.solution.positive_ranges(),
+        resolver.solution.decisions(),
+    )
+    return resolver.provider.choose_version(package, current_range)
+
+
+def absorb_pending_clauses(resolver: Resolver[Any, Any]) -> bool:
+    """Drain provider-queued incompatibilities into the formula.
+
+    Look-ahead providers push binary clauses like
+    ``{candidate==v, blocking_decision==w}`` instead of relying on the
+    broader ``NO_VERSIONS`` clause.  Returns True so the caller can suppress
+    the default ``NO_VERSIONS`` clause this turn.
+    """
+    clauses = list(resolver.provider.consume_pending_clauses())
+    for incompatibility in clauses:
+        add_incompatibility(resolver, incompatibility)
+    return bool(clauses)
+
+
+def record_no_versions(
+    resolver: Resolver[Any, Any], package: Any, *, had_pending: bool
+) -> None:
+    """Add the default ``NO_VERSIONS`` clause for ``package``.
+
+    Skipped when the provider already supplied context-aware clauses;
+    otherwise the broad clause would persist past the backjump that lifts
+    the supporting decisions.
+    """
+    if had_pending:
+        return
+
+    current_range = resolver.solution.get(package) or resolver.range_type.full()
+    resolver.observer.on_no_versions(package, current_range)
+    add_incompatibility(
+        resolver,
+        Incompatibility(
+            [Term(package, current_range, positive=True)],
+            cause=IncompatibilityCause.NO_VERSIONS,
+        ),
+    )

nab_resolver/errors.py

@@ -0,0 +1,36 @@
+"""Resolution error types.
+
+Defines the exception raised when the resolver proves that no valid
+solution exists, along with the derivation tree for error reporting.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .types import Incompatibility
+
+__all__ = [
+    "ResolutionError",
+]
+
+
+class ResolutionError(Exception):
+    """Resolution failed: no valid solution exists.
+
+    The ``incompatibility`` attribute holds the root incompatibility
+    whose derivation tree explains why resolution failed. Walk
+    ``cause_left`` and ``cause_right`` to trace the full proof.
+
+    Reference: https://github.com/dart-lang/pub/blob/master/doc/solver.md#error-reporting
+    """
+
+    def __init__(
+        self,
+        message: str,
+        incompatibility: Incompatibility[Any, Any] | None = None,
+    ) -> None:
+        """Create a resolution error with an optional incompatibility proof."""
+        super().__init__(message)
+        self.incompatibility = incompatibility