relay-flow 0.0.1 → 0.2.0-alpha

package/internal/repo/service.go

@@ -0,0 +1,216 @@
+package repo
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// ActiveRuns reports whether any run of a repo is active.
+type ActiveRuns interface {
+	HasActiveRepo(context.Context, string) (bool, error)
+}
+
+// WorkflowRefs reports whether any stored workflow references a repo.
+type WorkflowRefs interface {
+	ReferencesRepo(string) bool
+}
+
+// ServiceConfig wires the repo service to the machine config, runner, task
+// factory, and consumer query interfaces.
+type ServiceConfig struct {
+	ConfigPath string
+	TaskPlugin string
+	Runner     runner.Runner
+	Active     ActiveRuns
+	Workflows  WorkflowRefs
+}
+
+type Service struct {
+	cfgPath    string
+	taskPlugin string
+	runner     runner.Runner
+	active     ActiveRuns
+	workflows  WorkflowRefs
+	reg        *Registry
+}
+
+func NewService(cfg ServiceConfig) *Service {
+	return NewServiceWithRegistry(cfg, NewRegistry())
+}
+
+// NewServiceWithRegistry is NewService with a caller-supplied in-memory
+// Registry, letting the composition root share one repo set between the
+// engine, pollers, and HTTP handlers. Existing callers use NewService.
+func NewServiceWithRegistry(cfg ServiceConfig, reg *Registry) *Service {
+	return &Service{
+		cfgPath:    cfg.ConfigPath,
+		taskPlugin: cfg.TaskPlugin,
+		runner:     cfg.Runner,
+		active:     cfg.Active,
+		workflows:  cfg.Workflows,
+		reg:        reg,
+	}
+}
+
+// Registry exposes the in-memory repo set for wiring (poller group, binding).
+func (s *Service) Registry() *Registry {
+	return s.reg
+}
+
+func (s *Service) Discover(ctx context.Context) ([]runner.RepoCandidate, error) {
+	return s.runner.DiscoverRepos(ctx)
+}
+
+// RequiredRepoKeys delegates to the task factory's method of the same name.
+func (s *Service) RequiredRepoKeys() []string {
+	keys, err := task.RequiredRepoKeys(s.taskPlugin)
+	if err != nil {
+		return nil
+	}
+	return keys
+}
+
+type RegisterInput struct {
+	Name       string
+	Path       string
+	TaskConfig config.RawValues
+}
+
+// Register validates the runner repo, required task values, task-system
+// connectivity, duplicate names, canonical paths, and duplicate canonical
+// task scope before atomically writing machine config.
+func (s *Service) Register(ctx context.Context, input RegisterInput) (Info, error) {
+	if input.Name == "" {
+		return Info{}, fmt.Errorf("repo: name is required")
+	}
+	cfg, err := config.LoadMachine(s.cfgPath)
+	if err != nil {
+		return Info{}, err
+	}
+	if _, exists := cfg.Repos[input.Name]; exists {
+		return Info{}, fmt.Errorf("repo %q is already registered", input.Name)
+	}
+	canon := canonicalPath(input.Path)
+	for name, r := range cfg.Repos {
+		if canonicalPath(r.Path) == canon {
+			return Info{}, fmt.Errorf("repo path %q is already registered as %q", input.Path, name)
+		}
+	}
+	// Required repo keys must be present before any remote validation.
+	keys, err := task.RequiredRepoKeys(s.taskPlugin)
+	if err != nil {
+		return Info{}, err
+	}
+	for _, k := range keys {
+		v, ok := input.TaskConfig[k]
+		if !ok || v == nil || v == "" {
+			return Info{}, fmt.Errorf("repo %q: required task config key %q is missing", input.Name, k)
+		}
+	}
+	// Duplicate canonical task scope: compute this repo's scope and compare
+	// against every registered repo's scope.
+	newScope, err := task.TaskScopeKey(s.taskPlugin, cfg.TaskConfig, input.TaskConfig)
+	if err != nil {
+		return Info{}, fmt.Errorf("repo %q: %w", input.Name, err)
+	}
+	for name, r := range cfg.Repos {
+		scope, err := task.TaskScopeKey(s.taskPlugin, cfg.TaskConfig, r.TaskConfig)
+		if err != nil {
+			return Info{}, fmt.Errorf("repo %q: derive scope of registered repo %q: %w", input.Name, name, err)
+		}
+		if scope == newScope {
+			return Info{}, fmt.Errorf("repo %q: task scope already used by repo %q", input.Name, name)
+		}
+	}
+	// Runner validates the repo.
+	if err := s.runner.ValidateRepo(ctx, input.Name, input.Path); err != nil {
+		return Info{}, fmt.Errorf("repo %q: runner validation: %w", input.Name, err)
+	}
+	// Task-system connectivity: construct the repo-bound System.
+	sys, err := task.New(ctx, s.taskPlugin, task.RepoSpec{
+		Name:       input.Name,
+		Path:       input.Path,
+		RootConfig: cfg.TaskConfig,
+		RepoConfig: input.TaskConfig,
+	})
+	if err != nil {
+		return Info{}, fmt.Errorf("repo %q: task system connectivity: %w", input.Name, err)
+	}
+	// Persist atomically, then update the in-memory registry.
+	r := config.Repo{Path: input.Path, TaskConfig: input.TaskConfig}
+	if cfg.Repos == nil {
+		cfg.Repos = map[string]config.Repo{}
+	}
+	cfg.Repos[input.Name] = r
+	if err := config.SaveMachine(s.cfgPath, cfg); err != nil {
+		return Info{}, err
+	}
+	rp := &Repo{Name: input.Name, Path: input.Path, TaskConfig: input.TaskConfig, TaskSystem: sys}
+	s.reg.Replace(rp)
+	return rp.Info(), nil
+}
+
+// Remove deletes a registered repo. Removal is rejected while a stored
+// workflow references the repo or an active run uses it.
+func (s *Service) Remove(ctx context.Context, name string) error {
+	if s.workflows.ReferencesRepo(name) {
+		return fmt.Errorf("repo %q is referenced by a stored workflow; removal is rejected", name)
+	}
+	active, err := s.active.HasActiveRepo(ctx, name)
+	if err != nil {
+		return fmt.Errorf("check active runs for repo %q: %w", name, err)
+	}
+	if active {
+		return fmt.Errorf("repo %q has active runs; removal is rejected", name)
+	}
+	cfg, err := config.LoadMachine(s.cfgPath)
+	if err != nil {
+		return err
+	}
+	if _, ok := cfg.Repos[name]; !ok {
+		return fmt.Errorf("repo %q is not registered", name)
+	}
+	delete(cfg.Repos, name)
+	if err := config.SaveMachine(s.cfgPath, cfg); err != nil {
+		return err
+	}
+	s.reg.Remove(name)
+	return nil
+}
+
+func (s *Service) Get(name string) (Info, error) {
+	rp, ok := s.reg.Get(name)
+	if ok {
+		return rp.Info(), nil
+	}
+	cfg, err := config.LoadMachine(s.cfgPath)
+	if err != nil {
+		return Info{}, err
+	}
+	r, ok := cfg.Repos[name]
+	if !ok {
+		return Info{}, fmt.Errorf("repo %q is not registered", name)
+	}
+	return Info{Name: name, Path: r.Path, TaskConfig: r.TaskConfig}, nil
+}
+
+func (s *Service) List() []Info {
+	out := []Info{}
+	for _, rp := range s.reg.List() {
+		out = append(out, rp.Info())
+	}
+	return out
+}
+
+func canonicalPath(p string) string {
+	abs, err := filepath.Abs(p)
+	if err != nil {
+		return filepath.Clean(p)
+	}
+	return filepath.Clean(abs)
+}

package/internal/repo/service_test.go

@@ -0,0 +1,298 @@
+package repo_test
+
+import (
+	"context"
+	"errors"
+	"path/filepath"
+	"sync"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/task"
+)
+
+// 3.32-3.33: repo registration/removal per specs/workflow-repo-management
+// "Repos are registered independently" and "Repo removal protects
+// references".
+
+type fakeRunnerDiscovery struct {
+	candidates []runner.RepoCandidate
+	validErr   error
+}
+
+func (f *fakeRunnerDiscovery) DiscoverRepos(context.Context) ([]runner.RepoCandidate, error) {
+	return f.candidates, nil
+}
+func (f *fakeRunnerDiscovery) ValidateRepo(_ context.Context, _, _ string) error { return f.validErr }
+func (f *fakeRunnerDiscovery) EnsureEnvironment(context.Context, runner.RunSpec) (runner.Environment, error) {
+	return runner.Environment{}, nil
+}
+func (f *fakeRunnerDiscovery) FindTerminal(context.Context, runner.Environment, string) (runner.Terminal, bool, error) {
+	return runner.Terminal{}, false, nil
+}
+func (f *fakeRunnerDiscovery) InspectTerminal(context.Context, runner.Terminal) (runner.Terminal, bool, error) {
+	return runner.Terminal{}, false, nil
+}
+func (f *fakeRunnerDiscovery) SendTerminal(context.Context, runner.Terminal, string) error {
+	return nil
+}
+func (f *fakeRunnerDiscovery) CreateTerminal(context.Context, runner.Environment, string, runner.Command) (runner.Terminal, error) {
+	return runner.Terminal{}, nil
+}
+func (f *fakeRunnerDiscovery) CloseTerminal(context.Context, runner.Terminal) error { return nil }
+func (f *fakeRunnerDiscovery) EnsureTerminal(context.Context, runner.Environment, string, runner.Command) (runner.Terminal, error) {
+	return runner.Terminal{}, nil
+}
+func (f *fakeRunnerDiscovery) CloseTerminals(context.Context, runner.RunSpec) error { return nil }
+func (f *fakeRunnerDiscovery) CleanupRun(context.Context, runner.RunSpec) error     { return nil }
+
+// fakeActiveRuns / fakeWorkflowRefs implement the consumer interfaces.
+type fakeActiveRuns struct{ repos map[string]bool }
+
+// fakeTaskSystem is a minimal working task.System for connectivity success.
+type fakeTaskSystem struct{ task.System }
+
+func (fakeTaskSystem) Poll(context.Context) ([]task.Ticket, error) { return nil, nil }
+
+func newFakeSystem() task.System { return fakeTaskSystem{} }
+
+func (f *fakeActiveRuns) HasActiveRepo(_ context.Context, name string) (bool, error) {
+	return f.repos[name], nil
+}
+func (f *fakeActiveRuns) set(name string, on bool) { f.repos[name] = on }
+
+type fakeWorkflowRefs struct{ refs map[string]bool }
+
+func (f *fakeWorkflowRefs) ReferencesRepo(name string) bool { return f.refs[name] }
+func (f *fakeWorkflowRefs) set(name string, on bool)        { f.refs[name] = on }
+
+// The test task factory declares required repo keys and a canonical scope
+// derived from root+repo config; New returns a working in-memory System so
+// successful registration validates connectivity. Registered exactly once
+// for the whole package (duplicate registration panics by design).
+var registerTestFactoryOnce = sync.Once{}
+
+func registerTestTaskFactory(t *testing.T) {
+	t.Helper()
+	registerTestFactoryOnce.Do(func() {
+		task.Register("testjira", task.Factory{
+			RequiredRepoKeys: func() []string { return []string{"project", "component"} },
+			TaskScopeKey: func(root, repoCfg config.RawValues) (string, error) {
+				proj, _ := repoCfg["project"].(string)
+				comp, _ := repoCfg["component"].(string)
+				if proj == "" || comp == "" {
+					return "", errors.New("project and component required")
+				}
+				return "site/" + proj + "/" + comp, nil
+			},
+			New: func(_ context.Context, spec task.RepoSpec) (task.System, error) {
+				if spec.Name == "" {
+					return nil, errors.New("task system unreachable: empty repo name")
+				}
+				return newFakeSystem(), nil
+			},
+		})
+	})
+}
+
+type serviceFixture struct {
+	svc     *repo.Service
+	cfgPath string
+	active  *fakeActiveRuns
+	wfRefs  *fakeWorkflowRefs
+}
+
+func newServiceFixture(t *testing.T, rn runner.Runner) serviceFixture {
+	t.Helper()
+	registerTestTaskFactory(t)
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.yaml")
+	cfg := &config.Machine{
+		TaskPlugin: "testjira", RunnerPlugin: "orca", HarnessPlugin: "opencode",
+		Repos: map[string]config.Repo{},
+	}
+	if err := config.SaveMachine(cfgPath, cfg); err != nil {
+		t.Fatal(err)
+	}
+	active := &fakeActiveRuns{repos: map[string]bool{}}
+	wfRefs := &fakeWorkflowRefs{refs: map[string]bool{}}
+	svc := repo.NewService(repo.ServiceConfig{
+		ConfigPath: cfgPath,
+		TaskPlugin: "testjira",
+		Runner:     rn,
+		Active:     active,
+		Workflows:  wfRefs,
+	})
+	return serviceFixture{svc: svc, cfgPath: cfgPath, active: active, wfRefs: wfRefs}
+}
+
+func TestDiscoverDelegatesToRunner(t *testing.T) {
+	rn := &fakeRunnerDiscovery{candidates: []runner.RepoCandidate{{Name: "payments", Path: "/srv/payments"}}}
+	fx := newServiceFixture(t, rn)
+	got, err := fx.svc.Discover(context.Background())
+	if err != nil || len(got) != 1 || got[0].Name != "payments" {
+		t.Fatalf("Discover = %v, %v", got, err)
+	}
+}
+
+func TestRequiredRepoKeysDelegated(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	keys := fx.svc.RequiredRepoKeys()
+	if len(keys) != 2 || keys[0] != "project" || keys[1] != "component" {
+		t.Fatalf("RequiredRepoKeys = %v, want [project component]", keys)
+	}
+}
+
+func TestRegisterMissingRequiredKeyFails(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	// Missing "component".
+	_, err := fx.svc.Register(context.Background(), repo.RegisterInput{
+		Name: "payments", Path: "/srv/payments",
+		TaskConfig: config.RawValues{"project": "PAY"},
+	})
+	if err == nil {
+		t.Fatal("registration succeeded without a required repo key")
+	}
+	// Machine config unchanged.
+	cfg, _ := config.LoadMachine(fx.cfgPath)
+	if len(cfg.Repos) != 0 {
+		t.Fatal("machine config changed despite failed registration")
+	}
+}
+
+func TestRegisterRejectsDuplicateName(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	in := repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}
+	if _, err := fx.svc.Register(context.Background(), in); err != nil {
+		t.Fatalf("first Register failed: %v", err)
+	}
+	if _, err := fx.svc.Register(context.Background(), in); err == nil {
+		t.Fatal("duplicate repo name accepted")
+	}
+}
+
+func TestRegisterRejectsDuplicateCanonicalPath(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	okCfg := config.RawValues{"project": "PAY", "component": "api"}
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: okCfg}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "pay2", Path: "/srv/payments/./", TaskConfig: config.RawValues{"project": "OT", "component": "x"}}); err == nil {
+		t.Fatal("duplicate canonical path accepted")
+	}
+}
+
+func TestRegisterRejectsDuplicateTaskScope(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	scope := config.RawValues{"project": "PAY", "component": "api"}
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: scope}); err != nil {
+		t.Fatal(err)
+	}
+	// A different repo path but the same Jira site/project/component scope.
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "other", Path: "/srv/other", TaskConfig: scope}); err == nil {
+		t.Fatal("duplicate task-system scope accepted")
+	}
+}
+
+func TestRegisterValidatesRunnerRepo(t *testing.T) {
+	rn := &fakeRunnerDiscovery{validErr: errInvalidRepo{}}
+	fx := newServiceFixture(t, rn)
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "bad", Path: "/nope", TaskConfig: config.RawValues{"project": "P", "component": "c"}}); err == nil {
+		t.Fatal("registration succeeded despite runner validation failure")
+	}
+}
+
+func TestRegisterValidatesTaskConnectivity(t *testing.T) {
+	// The task factory's New is invoked to validate connectivity; its error
+	// must reject registration before persisting.
+	task.Register("failingtask", task.Factory{
+		RequiredRepoKeys: func() []string { return []string{"project"} },
+		TaskScopeKey:     func(_, repoCfg config.RawValues) (string, error) { return "s/" + repoCfg["project"].(string), nil },
+		New: func(context.Context, task.RepoSpec) (task.System, error) {
+			return nil, errors.New("jira unreachable")
+		},
+	})
+	dir := t.TempDir()
+	cfgPath := filepath.Join(dir, "config.yaml")
+	cfg := &config.Machine{TaskPlugin: "failingtask", RunnerPlugin: "orca", HarnessPlugin: "opencode", Repos: map[string]config.Repo{}}
+	if err := config.SaveMachine(cfgPath, cfg); err != nil {
+		t.Fatal(err)
+	}
+	svc := repo.NewService(repo.ServiceConfig{
+		ConfigPath: cfgPath, TaskPlugin: "failingtask",
+		Runner: &fakeRunnerDiscovery{}, Active: &fakeActiveRuns{repos: map[string]bool{}}, Workflows: &fakeWorkflowRefs{refs: map[string]bool{}},
+	})
+	_, err := svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY"}})
+	if err == nil {
+		t.Fatal("registration succeeded despite task connectivity failure")
+	}
+	cfg2, _ := config.LoadMachine(cfgPath)
+	if len(cfg2.Repos) != 0 {
+		t.Fatal("machine config persisted despite connectivity validation failure")
+	}
+}
+
+type errInvalidRepo struct{}
+
+func (errInvalidRepo) Error() string { return "invalid repo" }
+
+func TestRegisterAtomicallyPersists(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}); err != nil {
+		t.Fatal(err)
+	}
+	cfg, err := config.LoadMachine(fx.cfgPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	r, ok := cfg.Repos["payments"]
+	if !ok || r.Path != "/srv/payments" {
+		t.Fatalf("repo not persisted: %+v", cfg.Repos)
+	}
+	if r.TaskConfig["project"] != "PAY" {
+		t.Fatalf("repo taskConfig not persisted: %+v", r.TaskConfig)
+	}
+}
+
+func TestRemoveStopsPollerAndRemoves(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := fx.svc.Remove(context.Background(), "payments"); err != nil {
+		t.Fatalf("Remove failed: %v", err)
+	}
+	if _, err := fx.svc.Get("payments"); err == nil {
+		t.Fatal("removed repo still returned by Get")
+	}
+	// The repo's poller is stopped: the registry no longer lists it.
+	for _, info := range fx.svc.List() {
+		if info.Name == "payments" {
+			t.Fatal("removed repo still listed (poller not stopped)")
+		}
+	}
+}
+
+func TestRemoveRejectedWhileWorkflowReferences(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}); err != nil {
+		t.Fatal(err)
+	}
+	fx.wfRefs.set("payments", true)
+	if err := fx.svc.Remove(context.Background(), "payments"); err == nil {
+		t.Fatal("removal accepted while a stored workflow references the repo")
+	}
+}
+
+func TestRemoveRejectedWhileRunActive(t *testing.T) {
+	fx := newServiceFixture(t, &fakeRunnerDiscovery{})
+	if _, err := fx.svc.Register(context.Background(), repo.RegisterInput{Name: "payments", Path: "/srv/payments", TaskConfig: config.RawValues{"project": "PAY", "component": "api"}}); err != nil {
+		t.Fatal(err)
+	}
+	fx.active.set("payments", true)
+	if err := fx.svc.Remove(context.Background(), "payments"); err == nil {
+		t.Fatal("removal accepted while an active run uses the repo")
+	}
+}

package/internal/retry/retry.go

@@ -0,0 +1,118 @@
+// Package retry provides the single shared error classification and backoff
+// policy used by durable activities, repo pollers, and (mirrored) the
+// TypeScript harness plugin.
+package retry
+
+import (
+	"context"
+	"errors"
+	"math"
+	"time"
+)
+
+// Kind classifies a failure for retry purposes.
+type Kind string
+
+const (
+	// Transient failures are retried with backoff until they succeed.
+	Transient Kind = "transient"
+	// Conflict failures indicate a manual task-system change; the run blocks
+	// and retries with the shared backoff until external state becomes
+	// compatible again.
+	Conflict Kind = "conflict"
+)
+
+// Failure is the classified form of an error.
+type Failure struct {
+	Kind    Kind   `json:"kind"`
+	Message string `json:"message"`
+}
+
+// conflictError marks err as a Conflict.
+type conflictError struct{ err error }
+
+func (e *conflictError) Error() string { return e.err.Error() }
+func (e *conflictError) Unwrap() error { return e.err }
+
+// ConflictError wraps err so Classify reports Kind=Conflict.
+func ConflictError(err error) error {
+	if err == nil {
+		return nil
+	}
+	return &conflictError{err: err}
+}
+
+// Classify returns the Failure for err. nil yields a zero Failure.
+func Classify(err error) Failure {
+	if err == nil {
+		return Failure{}
+	}
+	kind := Transient
+	var ce *conflictError
+	if errors.As(err, &ce) {
+		kind = Conflict
+	}
+	return Failure{Kind: kind, Message: err.Error()}
+}
+
+// BackoffPolicy computes exponential backoff delays with jitter.
+type BackoffPolicy struct {
+	Initial time.Duration
+	Maximum time.Duration
+	Factor  float64
+	Jitter  float64
+}
+
+// DefaultBackoffPolicy is the shared policy: 2s initial, factor 2, jitter 0.2,
+// capped at 5 minutes.
+var DefaultBackoffPolicy = BackoffPolicy{
+	Initial: 2 * time.Second,
+	Maximum: 5 * time.Minute,
+	Factor:  2,
+	Jitter:  0.2,
+}
+
+// Delay returns the delay before the given attempt (0-based). random must be
+// in [0,1) and supplies the jitter so durable callers can stay replay-safe.
+func (p BackoffPolicy) Delay(attempt int, random float64) time.Duration {
+	if attempt < 0 {
+		attempt = 0
+	}
+	base := float64(p.Initial) * math.Pow(p.Factor, float64(attempt))
+	if base > float64(p.Maximum) {
+		base = float64(p.Maximum)
+	}
+	// Symmetric jitter in [1-Jitter, 1+Jitter].
+	j := (random*2 - 1) * p.Jitter
+	d := time.Duration(base * (1 + j))
+	if d < 0 {
+		return 0
+	}
+	if d > p.Maximum {
+		return p.Maximum
+	}
+	return d
+}
+
+// Do runs fn with the shared backoff until it succeeds, returns a Conflict,
+// or ctx is canceled. Conflict failures are returned to the caller so the
+// run can mark itself blocked.
+func Do(ctx context.Context, policy BackoffPolicy, fn func() error) error {
+	attempt := 0
+	for {
+		err := fn()
+		if err == nil {
+			return nil
+		}
+		if Classify(err).Kind == Conflict {
+			return err
+		}
+		delay := policy.Delay(attempt, 0.5)
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(delay):
+		}
+		attempt++
+	}
+}