Add structured logging hooks for solver diagnostics

Author: seuros

README.md

@@ -14,6 +14,7 @@ A comprehensive Go implementation of the PubGrub version solving algorithm with
 - 🚀 **CDCL Solver** - Conflict-driven clause learning with unit propagation
 - 🧪 **Well Tested** - Comprehensive test suite with strong coverage
 - ⚡ **Production Ready** - Handles complex dependency graphs efficiently
+- 🪵 **Structured Debug Logging** - Plug in `log/slog` via `WithLogger` for rich solver traces
 
 ## Origin
 
@@ -128,6 +129,37 @@ func main() {
 }
 ```
 
+### Debug Logging
+
+```go
+package main
+
+import (
+    "log/slog"
+    "os"
+
+    "github.com/contriboss/pubgrub-go"
+)
+
+func main() {
+    logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
+        Level: slog.LevelDebug,
+    }))
+
+    root := pubgrub.NewRootSource()
+    source := &pubgrub.InMemorySource{}
+
+    solver := pubgrub.NewSolverWithOptions(
+        []pubgrub.Source{root, source},
+        pubgrub.WithLogger(logger),
+    )
+
+    if _, err := solver.Solve(root.Term()); err != nil {
+        logger.Error("resolution failed", "err", err)
+    }
+}
+```
+
 ## Core Concepts
 
 ### Versions
@@ -365,7 +397,7 @@ Contributions welcome! Please:
 This package is derived from the tinyrange project:
 - **Original Repository:** https://github.com/tinyrange/tinyrange
 - **Original Package:** experimental/pubgrub
-- **Version:** v0.2.7 (Oct 27, 2025)
+- **Version:** v0.3.1 (Oct 31, 2025)
 - **Original Copyright:** Copyright 2024 The University of Queensland
 - **Original License:** Apache 2.0
 

assignment.go

@@ -15,6 +15,8 @@
 
 package pubgrub
 
+import "fmt"
+
 // assignmentKind distinguishes between decision and derivation assignments.
 // Decision assignments are explicit choices made by the solver (version selections).
 // Derivation assignments are constraints derived from incompatibilities via unit propagation.
@@ -49,3 +51,36 @@ type assignment struct {
 func (a *assignment) isDecision() bool {
 	return a.kind == assignmentDecision
 }
+
+// describe returns a compact string describing the assignment.
+// Used exclusively for debug logging to keep the hot path free of allocations.
+func (a *assignment) describe() string {
+	if a == nil {
+		return "<nil>"
+	}
+
+	kind := "derivation"
+	if a.isDecision() {
+		kind = "decision"
+	}
+
+	version := "<nil>"
+	if a.version != nil {
+		version = a.version.String()
+	}
+
+	desc := fmt.Sprintf("%s idx=%d lvl=%d kind=%s term=%s version=%s",
+		a.name.Value(), a.index, a.decisionLevel, kind, a.term.String(), version)
+
+	if a.allowed != nil {
+		desc += fmt.Sprintf(" allowed=%s", a.allowed.String())
+	}
+	if a.forbidden != nil {
+		desc += fmt.Sprintf(" forbidden=%s", a.forbidden.String())
+	}
+	if a.cause != nil {
+		desc += fmt.Sprintf(" cause=\"%s\"", a.cause.String())
+	}
+
+	return desc
+}

partial_solution.go

@@ -15,7 +15,11 @@
 
 package pubgrub
 
-import "errors"
+import (
+	"errors"
+	"fmt"
+	"strings"
+)
 
 // partialSolution maintains the evolving solution during dependency resolution.
 // It tracks assignments (decisions and derivations) organized by package name
@@ -326,6 +330,38 @@ func (ps *partialSolution) buildSolution() Solution {
 	return result
 }
 
+// snapshot returns a human-readable representation of the partial solution.
+// Intended for debug logging to understand solver state during complex conflicts.
+func (ps *partialSolution) snapshot() string {
+	var b strings.Builder
+	fmt.Fprintf(&b, "decision_level=%d next_index=%d assignments=%d\n", ps.decisionLvl, ps.nextIndex, len(ps.assignments))
+	for _, assign := range ps.assignments {
+		fmt.Fprintf(&b, "  %s\n", assign.describe())
+	}
+	return b.String()
+}
+
+// pendingPackages lists packages that have constraints but no decided version yet.
+// Used for diagnostics when analysing package selection order.
+func (ps *partialSolution) pendingPackages() []Name {
+	pending := make([]Name, 0)
+	seen := make(map[Name]bool)
+
+	for _, assign := range ps.assignments {
+		name := assign.name
+		if name == ps.root || seen[name] {
+			continue
+		}
+		seen[name] = true
+
+		if !ps.hasDecision(name) {
+			pending = append(pending, name)
+		}
+	}
+
+	return pending
+}
+
 // termSatisfiedBy checks if an assignment satisfies a term in an incompatibility.
 func termSatisfiedBy(term Term, assign *assignment) bool {
 	if assign == nil {
@@ -341,10 +377,10 @@ func termSatisfiedBy(term Term, assign *assignment) bool {
 			if assign.allowed == nil {
 				return false
 			}
-			return assign.allowed.IsSubset(required) || assign.allowed.IsDisjoint(required)
+			return assign.allowed.IsSubset(required)
 		}
 		if assign.allowed != nil {
-			return assign.allowed.IsSubset(required) || assign.allowed.IsDisjoint(required)
+			return assign.allowed.IsSubset(required)
 		}
 		return false
 	}
@@ -358,7 +394,7 @@ func termSatisfiedBy(term Term, assign *assignment) bool {
 		if assign.allowed == nil {
 			return false
 		}
-		return assign.allowed.IsDisjoint(forbidden) || assign.allowed.IsSubset(forbidden)
+		return assign.allowed.IsDisjoint(forbidden)
 	}
 
 	if assign.forbidden == nil {

partial_solution_test.go

@@ -0,0 +1,39 @@
+package pubgrub
+
+import "testing"
+
+func TestPartialSolutionPreviousDecisionLevel(t *testing.T) {
+	root := MakeName("root")
+	ps := newPartialSolution(root)
+	rootVersion := SimpleVersion("1.0.0")
+	ps.seedRoot(root, rootVersion)
+
+	a := MakeName("a")
+	aVersion := SimpleVersion("1.0.0")
+	ps.addDecision(a, aVersion)
+
+	b := MakeName("b")
+	bVersion := SimpleVersion("1.0.0")
+	assignB := ps.addDecision(b, bVersion)
+
+	inc := &Incompatibility{
+		Terms: []Term{
+			NewTerm(a, EqualsCondition{Version: aVersion}),
+			NewTerm(b, EqualsCondition{Version: bVersion}),
+		},
+		Kind: KindConflict,
+	}
+
+	satisfier := ps.satisfier(inc)
+	if satisfier == nil {
+		t.Fatalf("expected satisfier, got nil")
+	}
+	if satisfier != assignB {
+		t.Fatalf("expected satisfier to be assignment for %s, got %s", b.Value(), satisfier.name.Value())
+	}
+
+	prev := ps.previousDecisionLevel(inc, satisfier)
+	if prev != 1 {
+		t.Fatalf("expected previous decision level 1, got %d", prev)
+	}
+}

solver.go

@@ -15,6 +15,8 @@
 
 package pubgrub
 
+import "strings"
+
 // Solver implements the PubGrub dependency resolution algorithm with CDCL.
 //
 // The solver uses Conflict-Driven Clause Learning (CDCL) to efficiently
@@ -118,6 +120,7 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 
 	assign := state.partial.seedRoot(root.Name, version)
 	state.markAssigned(root.Name)
+	state.traceAssignment("seed", assign)
 
 	s.debug("seeded root", "package", root.Name, "version", version)
 
@@ -179,7 +182,18 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 			return state.partial.buildSolution(), nil
 		}
 
-		s.debug("selecting package", "step", steps, "package", nextPkg)
+		allowed := state.partial.allowedSet(nextPkg)
+		allowedStr := "<nil>"
+		if allowed != nil {
+			allowedStr = allowed.String()
+		}
+		pending := state.partial.pendingPackages()
+		s.debug("selecting package",
+			"step", steps,
+			"package", nextPkg,
+			"allowed", allowedStr,
+			"pending", joinNameValues(pending),
+		)
 
 		ver, found, err := state.pickVersion(nextPkg)
 		if err != nil {
@@ -199,6 +213,7 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 		s.debug("making decision", "step", steps, "package", nextPkg, "version", ver)
 
 		assign := state.partial.addDecision(nextPkg, ver)
+		state.traceAssignment("decision", assign)
 		state.markAssigned(assign.name)
 
 		deps, err := s.Source.GetDependencies(nextPkg, ver)
@@ -217,6 +232,17 @@ func (s *Solver) Solve(root Term) (Solution, error) {
 	}
 }
 
+func joinNameValues(names []Name) string {
+	if len(names) == 0 {
+		return ""
+	}
+	values := make([]string, len(names))
+	for i, name := range names {
+		values[i] = name.Value()
+	}
+	return strings.Join(values, ",")
+}
+
 func extractDecisionVersion(root Term) (Version, error) {
 	if !root.Positive {
 		return nil, &VersionError{Package: root.Name, Message: "root term must be positive"}