From 8caa602bae71587ed617e6671a856af09812277e Mon Sep 17 00:00:00 2001 From: Jonathan Yoder Date: Wed, 18 Nov 2026 10:36:16 -0500 Subject: [PATCH 1/2] Bound the UpgradeRoots pass in solver steps, not only time Time bounds make pins depend on host load. A step budget gives the same pins for the same inputs on every run. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 + resolver/export_test.go | 9 ++ resolver/resolver.go | 66 +++++++- resolver/upgrade.go | 41 ++++- resolver/upgrade_steps_test.go | 284 +++++++++++++++++++++++++++++++++ 5 files changed, 391 insertions(+), 13 deletions(-) create mode 100644 resolver/upgrade_steps_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index dc2e189..b6a5c06 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ served it. ## [Unreleased] +### Added + +- `Options.UpgradeStepFactor` and `Options.UpgradeMaxSteps` bound the `UpgradeRoots` pass in solver steps instead of time: its re-solves together may take this many times the first solve's steps, or this many steps. Steps do not depend on the clock, so the same inputs give the same pins on every run, even on a loaded machine. The time bounds still work and can be kept as a backstop, but an answer they cut can differ between runs. With neither new option set, nothing changes. + ## [0.25.0] - 2026-11-14 ### Changed diff --git a/resolver/export_test.go b/resolver/export_test.go index 3b2a892..9c7bb88 100644 --- a/resolver/export_test.go +++ b/resolver/export_test.go @@ -46,3 +46,12 @@ func SetClock(f func() time.Time) (restore func()) { now = f return func() { now = time.Now } } + +// RecordSteps records the solver steps of each resolution Resolve runs, the +// first solve then each upgrade re-solve, until restore is called. +// Not safe with parallel tests. +func RecordSteps() (got func() []int, restore func()) { + var all []int + onSteps = func(n int) { all = append(all, n) } + return func() []int { return all }, func() { onSteps = nil } +} diff --git a/resolver/resolver.go b/resolver/resolver.go index b9380dd..b30bdd3 100644 --- a/resolver/resolver.go +++ b/resolver/resolver.go @@ -197,8 +197,9 @@ type Options struct { // ones are bounded. Zero (the default) means no time bound. // // The bound reads the clock, so with it set the answer can differ between - // runs on a loaded machine. It never fails a resolution: the best answer so - // far is returned, as when the budget or ctx ends. + // runs on a loaded machine; UpgradeStepFactor is the repeatable bound. It + // never fails a resolution: the best answer so far is returned, as when the + // budget or ctx ends. UpgradeTimeFactor float64 // UpgradeMaxTime, when above zero, is an absolute cap on the time the @@ -206,6 +207,24 @@ type Options struct { // stopped at the cap. It applies together with UpgradeTimeFactor; whichever // limit is reached first ends the pass. Zero (the default) means no cap. UpgradeMaxTime time.Duration + + // UpgradeStepFactor, when above zero, bounds the UpgradeRoots pass in + // solver steps: all its re-solves together may take this many times the + // steps the first solve took. A step is one round of the solver's main loop + // or one step of conflict resolution. A re-solve that reaches the bound is + // stopped, counts as no gain, and ends the pass. Zero (the default) means + // no step bound. + // + // Unlike the time bounds, steps do not depend on the clock or machine load, + // so the same inputs give the same answer every run. Use a step bound to + // limit the pass; keep a time bound only as a backstop, since an answer it + // cuts can still differ between runs. + UpgradeStepFactor float64 + + // UpgradeMaxSteps, when above zero, is an absolute cap on the solver steps + // all UpgradeRoots re-solves may take together. It applies together with + // UpgradeStepFactor; the lower bound wins. Zero (the default) means no cap. + UpgradeMaxSteps int } // Resolution is a successful resolution: one version chosen for every package @@ -370,11 +389,36 @@ func Resolve( opts Options, ) (*Resolution, error) { start := now() - res, err := resolveOnce(ctx, reqs, idx, opts) + steps := &stepMeter{} + res, err := resolveOnce(ctx, reqs, idx, opts, steps) if err != nil || opts.UpgradeRoots <= 0 { return res, err } - return upgradeRoots(ctx, reqs, idx, opts, res, now().Sub(start)), nil + return upgradeRoots(ctx, reqs, idx, opts, res, now().Sub(start), steps.used), nil +} + +// stepMeter counts the solver steps of one resolution, across all its solves, +// and stops it once limit steps are used. Zero limit means no limit. +type stepMeter struct { + used, limit int +} + +// errStepBudget stops a re-solve that used the upgrade pass's last step. +var errStepBudget = errors.New("resolver: upgrade step budget spent") + +// interrupt is the solver's Interrupt: the solver calls it once per step, +// on one goroutine, so the count depends only on the inputs. +func (m *stepMeter) interrupt(ctx context.Context) func() error { + return func() error { + if err := ctx.Err(); err != nil { + return err + } + if m.limit > 0 && m.used >= m.limit { + return errStepBudget + } + m.used++ + return nil + } } // providerOptions maps Options to the provider's options for one resolution. @@ -396,13 +440,18 @@ func providerOptions(reqs []requirement.Requirement, opts Options) provider.Opti } } -// resolveOnce is one resolution, with no upgrade pass. +// resolveOnce is one resolution, with no upgrade pass. steps counts its +// solver steps and may stop it. func resolveOnce( ctx context.Context, reqs []requirement.Requirement, idx index.MetadataIndex, opts Options, + steps *stepMeter, ) (*Resolution, error) { + if onSteps != nil { + defer func() { onSteps(steps.used) }() + } if err := validate(opts); err != nil { return nil, err } @@ -436,8 +485,8 @@ func resolveOnce( s.ClashThreshold = opts.ClashThreshold s.ClashFirst = opts.ClashFirst s.MaxConflicts = opts.MaxConflicts - // Stop on cancel or deadline; the error unwraps to ctx.Err(). - s.Interrupt = ctx.Err + // Stop on cancel, deadline or step budget; the error unwraps to the cause. + s.Interrupt = steps.interrupt(ctx) if onSolver != nil { onSolver(s) } @@ -506,6 +555,9 @@ var now = time.Now // onSolve, when set by a test, is called before each solve. var onSolve func() +// onSteps, when set by a test, gets the steps each resolveOnce used. +var onSteps func(int) + // onSolver, when set by a test, sees each Solver after Resolve has configured it. var onSolver func(*solver.Solver[provider.Package, pep440set.Set]) diff --git a/resolver/upgrade.go b/resolver/upgrade.go index 95e2b42..8fb2b7b 100644 --- a/resolver/upgrade.go +++ b/resolver/upgrade.go @@ -222,9 +222,27 @@ func upgradeTimeLimit(opts Options, baseDur time.Duration) (limit time.Duration, return limit, ok } +// upgradeStepLimit is how many solver steps the pass's re-solves may take in +// all, from the options and the first solve's steps. ok is false when neither +// bound is set. +func upgradeStepLimit(opts Options, baseSteps int) (limit int, ok bool) { + if opts.UpgradeMaxSteps > 0 { + limit, ok = opts.UpgradeMaxSteps, true + } + if opts.UpgradeStepFactor > 0 { + // A huge factor is no bound; it must not overflow the int. + if f := float64(baseSteps) * opts.UpgradeStepFactor; f < math.MaxInt { + if n := int(f); !ok || n < limit { + limit, ok = n, true + } + } + } + return limit, ok +} + // upgradeRoots is the pass behind Options.UpgradeRoots. base is a valid answer -// to reqs, and baseDur is how long it took; the result is base or a valid -// answer that scores strictly better. +// to reqs, and baseDur and baseSteps are what it took; the result is base or a +// valid answer that scores strictly better. func upgradeRoots( ctx context.Context, reqs []requirement.Requirement, @@ -232,12 +250,18 @@ func upgradeRoots( opts Options, base *Resolution, baseDur time.Duration, + baseSteps int, ) *Resolution { passStart := now() limit, timed := upgradeTimeLimit(opts, baseDur) - // cut is set once a re-solve is stopped by the bound; the pass then ends. + stepLimit, stepped := upgradeStepLimit(opts, baseSteps) + spent := 0 // solver steps the re-solves have used + // cut is set once a re-solve is stopped by the time bound; the pass then + // ends. A re-solve stopped by the step bound leaves spent at stepLimit. cut := false - timeUp := func() bool { return cut || (timed && now().Sub(passStart) >= limit) } + timeUp := func() bool { + return cut || (stepped && spent >= stepLimit) || (timed && now().Sub(passStart) >= limit) + } u := &usability{ p: provider.New(ctx, idx, providerOptions(reqs, opts)), memo: map[usableKey]bool{}, @@ -274,9 +298,14 @@ func upgradeRoots( defer cancel() solveCtx = c } - got, err := resolveOnce(solveCtx, all, idx, inner) + steps := &stepMeter{} + if stepped { + steps.limit = stepLimit - spent + } + got, err := resolveOnce(solveCtx, all, idx, inner, steps) + spent += steps.used if err != nil { - // Stopped by the bound, not the caller: no gain, and the pass ends. + // Stopped by the time bound, not the caller: no gain, and the pass ends. if ctx.Err() == nil && solveCtx.Err() != nil { cut = true } diff --git a/resolver/upgrade_steps_test.go b/resolver/upgrade_steps_test.go new file mode 100644 index 0000000..b30a250 --- /dev/null +++ b/resolver/upgrade_steps_test.go @@ -0,0 +1,284 @@ +// SPDX-License-Identifier: Apache-2.0 OR MIT + +package resolver_test + +import ( + "context" + "math" + "math/rand" + "reflect" + "runtime" + "sync" + "testing" + "time" + + "github.com/posit-dev/go-pyresolver/index" + "github.com/posit-dev/go-pyresolver/resolver" +) + +// resolveSteps resolves reqs with the pass on and returns the pins and the +// steps of each resolution: the first solve, then each re-solve. +func resolveSteps(t *testing.T, idx index.MetadataIndex, reqs []string, mutate func(*resolver.Options)) (map[string]string, []int) { + t.Helper() + got, restore := resolver.RecordSteps() + defer restore() + opts := testOptions(t) + opts.UpgradeRoots = 40 + mutate(&opts) + res, err := resolver.Resolve(context.Background(), mustRequirements(t, reqs...), idx, opts) + if err != nil { + t.Fatal(err) + } + return pins(t, res), got() +} + +func sum(xs []int) int { + n := 0 + for _, x := range xs { + n += x + } + return n +} + +// unbounded measures the pass with no bound: lateGain runs three re-solves +// (a fails, z gains, y fails). +func unbounded(t *testing.T) (base int, re []int) { + t.Helper() + idx, reqs := lateGain() + got, steps := resolveSteps(t, idx, reqs, func(*resolver.Options) {}) + if !reflect.DeepEqual(got, lateZ) || len(steps) != 4 { + t.Fatalf("unbounded: got %v with steps %v, want %v after 3 re-solves", got, steps, lateZ) + } + for _, n := range steps { + if n == 0 { + t.Fatalf("a resolution took no steps: %v", steps) + } + } + return steps[0], steps[1:] +} + +// The budget is shared by all re-solves: one step short of the first two +// re-solves cuts the second, which held the only gain. +func TestUpgradeMaxStepsIsChargedAcrossReSolves(t *testing.T) { + _, re := unbounded(t) + idx, reqs := lateGain() + + got, steps := resolveSteps(t, idx, reqs, func(o *resolver.Options) { o.UpgradeMaxSteps = re[0] + re[1] - 1 }) + if !reflect.DeepEqual(got, lateBase) { + t.Errorf("one step short: got %v, want the base %v", got, lateBase) + } + if want := []int{re[0], re[1] - 1}; !reflect.DeepEqual(steps[1:], want) { + t.Errorf("one step short: re-solve steps %v, want %v", steps[1:], want) + } + + got, steps = resolveSteps(t, idx, reqs, func(o *resolver.Options) { o.UpgradeMaxSteps = re[0] + re[1] }) + if !reflect.DeepEqual(got, lateZ) { + t.Errorf("exact budget: got %v, want %v", got, lateZ) + } + // The budget is spent, so the third re-solve never starts. + if !reflect.DeepEqual(steps[1:], re[:2]) { + t.Errorf("exact budget: re-solve steps %v, want %v", steps[1:], re[:2]) + } +} + +// The factor scales the first solve's steps, rounding down. +func TestUpgradeStepFactorScalesBaseSteps(t *testing.T) { + base, re := unbounded(t) + idx, reqs := lateGain() + for _, tc := range []struct { + name string + budget int + want map[string]string + }{ + {"short", re[0] + re[1] - 1, lateBase}, + {"exact", re[0] + re[1], lateZ}, + } { + factor := (float64(tc.budget) + 0.5) / float64(base) + got, steps := resolveSteps(t, idx, reqs, func(o *resolver.Options) { o.UpgradeStepFactor = factor }) + if !reflect.DeepEqual(got, tc.want) || sum(steps[1:]) != tc.budget { + t.Errorf("%s: got %v using %d steps, want %v using %d", tc.name, got, sum(steps[1:]), tc.want, tc.budget) + } + } +} + +// A budget of no steps returns the first answer and starts no re-solve. +func TestUpgradeZeroStepBudgetReturnsBase(t *testing.T) { + idx, reqs := lateGain() + for _, set := range []func(*resolver.Options){ + func(o *resolver.Options) { o.UpgradeStepFactor = 1e-9 }, + func(o *resolver.Options) { o.UpgradeStepFactor = math.SmallestNonzeroFloat64 }, + } { + got, steps := resolveSteps(t, idx, reqs, set) + if !reflect.DeepEqual(got, lateBase) || len(steps) != 1 { + t.Errorf("got %v after %d re-solves, want the base %v after none", got, len(steps)-1, lateBase) + } + } + // One step: the first re-solve starts and is cut. + got, steps := resolveSteps(t, idx, reqs, func(o *resolver.Options) { o.UpgradeMaxSteps = 1 }) + if !reflect.DeepEqual(got, lateBase) || !reflect.DeepEqual(steps[1:], []int{1}) { + t.Errorf("one step: got %v with re-solve steps %v", got, steps[1:]) + } +} + +// Zero, negative, NaN and huge bounds are no bound: the pass is unchanged. +func TestUpgradeStepBoundOffIsUnbounded(t *testing.T) { + _, re := unbounded(t) + idx, reqs := lateGain() + for _, set := range []func(*resolver.Options){ + func(o *resolver.Options) { o.UpgradeMaxSteps = -1 }, + func(o *resolver.Options) { o.UpgradeStepFactor = -1 }, + func(o *resolver.Options) { o.UpgradeStepFactor = math.NaN() }, + func(o *resolver.Options) { o.UpgradeStepFactor = math.Inf(1) }, + func(o *resolver.Options) { o.UpgradeStepFactor = math.MaxFloat64 }, + } { + got, steps := resolveSteps(t, idx, reqs, set) + if !reflect.DeepEqual(got, lateZ) || !reflect.DeepEqual(steps[1:], re) { + t.Errorf("got %v with re-solve steps %v, want %v with %v", got, steps[1:], lateZ, re) + } + } +} + +// The lower of the two step bounds wins. +func TestUpgradeStepBoundsCombine(t *testing.T) { + base, re := unbounded(t) + idx, reqs := lateGain() + short := re[0] + re[1] - 1 + for _, set := range []func(*resolver.Options){ + func(o *resolver.Options) { o.UpgradeMaxSteps = short; o.UpgradeStepFactor = 1000 }, + func(o *resolver.Options) { + o.UpgradeMaxSteps = 1 << 30 + o.UpgradeStepFactor = (float64(short) + 0.5) / float64(base) + }, + } { + got, steps := resolveSteps(t, idx, reqs, set) + if !reflect.DeepEqual(got, lateBase) || sum(steps[1:]) != short { + t.Errorf("got %v using %d steps, want %v using %d", got, sum(steps[1:]), lateBase, short) + } + } +} + +// loadClock is a clock that jumps a random amount on every read, standing in +// for a loaded machine. Each run gets its own jumps. +func loadClock(seed int64) func() time.Time { + rng := rand.New(rand.NewSource(seed)) + var mu sync.Mutex + at := time.Unix(0, 0) + return func() time.Time { + mu.Lock() + defer mu.Unlock() + at = at.Add(time.Duration(rng.Int63n(int64(time.Millisecond)))) + return at + } +} + +// busy keeps n goroutines spinning until stop is called. +func busy(n int) (stop func()) { + done := make(chan struct{}) + var wg sync.WaitGroup + for range n { + wg.Add(1) + go func() { + defer wg.Done() + for { + select { + case <-done: + return + default: + runtime.Gosched() + } + } + }() + } + return func() { close(done); wg.Wait() } +} + +// determinismCases are random indexes where the unbounded pass changes the +// answer, each with a step budget that cuts the pass partway. +func determinismCases(t *testing.T) []struct { + idx index.MetadataIndex + reqs []string + budget int +} { + t.Helper() + var out []struct { + idx index.MetadataIndex + reqs []string + budget int + } + for seed := int64(0); seed < 300 && len(out) < 12; seed++ { + rng := rand.New(rand.NewSource(seed)) + idx, reqs := randomIndex(rng, 4+rng.Intn(4)) + opts := testOptions(t) + if _, err := resolver.Resolve(context.Background(), mustRequirements(t, reqs...), idx, opts); err != nil { + continue + } + _, steps := resolveSteps(t, idx, reqs, func(*resolver.Options) {}) + if len(steps) < 3 { + continue // fewer than two re-solves: no budget cuts it partway + } + out = append(out, struct { + idx index.MetadataIndex + reqs []string + budget int + }{idx, reqs, sum(steps[1:]) / 2}) + } + if len(out) < 5 { + t.Fatalf("only %d cases with two or more re-solves", len(out)) + } + return out +} + +// With a step budget, the same inputs give the same pins and the same steps on +// every run, whatever the clock, GOMAXPROCS or other work on the machine. A +// time cap that the jumping clock never reaches is set too, as a caller would. +func TestUpgradeStepBudgetIsDeterministic(t *testing.T) { + cases := determinismCases(t) + runs := 20 + if raceEnabled { + runs = 5 + } + for i, c := range cases { + var first map[string]string + var firstSteps []int + for _, procs := range []int{1, 8} { + prev := runtime.GOMAXPROCS(procs) + stop := busy(4) + for run := range runs { + restore := resolver.SetClock(loadClock(int64(run))) + got, steps := resolveSteps(t, c.idx, c.reqs, func(o *resolver.Options) { + o.UpgradeMaxSteps = c.budget + o.UpgradeMaxTime = time.Hour + }) + restore() + if first == nil { + first, firstSteps = got, steps + continue + } + if !reflect.DeepEqual(got, first) || !reflect.DeepEqual(steps, firstSteps) { + t.Errorf("case %d GOMAXPROCS %d run %d: %v steps %v, first run %v steps %v", + i, procs, run, got, steps, first, firstSteps) + } + } + stop() + runtime.GOMAXPROCS(prev) + } + } +} + +// The jumping clock does move a time-bounded pass, so the test above would +// see a dependence on the clock if the step budget had one. +func TestUpgradeTimeBoundMovesWithLoadClock(t *testing.T) { + for _, c := range determinismCases(t) { + seen := map[int]bool{} + for run := range 20 { + restore := resolver.SetClock(loadClock(int64(run))) + _, steps := resolveSteps(t, c.idx, c.reqs, func(o *resolver.Options) { o.UpgradeTimeFactor = 1.5 }) + restore() + seen[len(steps)] = true + } + if len(seen) > 1 { + return + } + } + t.Error("no case started a different number of re-solves across runs: the clock is not exercised") +} From 3c7390253c7e4e2c9756bf3fd1356e3c32ac6f1c Mon Sep 17 00:00:00 2001 From: Jonathan Yoder Date: Wed, 18 Nov 2026 11:00:44 -0500 Subject: [PATCH 2/2] Never start an upgrade re-solve with no steps left Co-Authored-By: Claude Opus 5.5 --- resolver/upgrade.go | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/resolver/upgrade.go b/resolver/upgrade.go index 8fb2b7b..3e0f29d 100644 --- a/resolver/upgrade.go +++ b/resolver/upgrade.go @@ -289,6 +289,11 @@ func upgradeRoots( if err != nil { return nil } + // Callers check timeUp first, so this cannot fire; it keeps a zero + // meter limit, which means no limit, from ever reaching resolveOnce. + if stepped && spent >= stepLimit { + return nil + } budget-- all := append(slices.Clone(reqs), floor) solveCtx := ctx