relay-flow 0.0.1 → 0.2.0-alpha

package/internal/router/router.go

@@ -0,0 +1,83 @@
+// Package router is the pure Ticket Router. It has no Jira, SQLite, runner,
+// or goroutine dependency.
+package router
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// ErrNoMatch means an unclaimed ticket matches no workflow filter; the
+// polling handler ignores it.
+var ErrNoMatch = errors.New("ticket matches no workflow")
+
+// AmbiguousError means an unclaimed ticket matches more than one workflow.
+// No ticket mutation occurs.
+type AmbiguousError struct {
+	Ticket    string
+	Workflows []string
+}
+
+func (e *AmbiguousError) Error() string {
+	return fmt.Sprintf("ticket %s matches multiple workflows: %s", e.Ticket, strings.Join(e.Workflows, ", "))
+}
+
+// InvalidClaimError means the ticket carries several workflow claims, or a
+// claim naming an unknown workflow or one not registered for the repo.
+type InvalidClaimError struct {
+	Ticket   string
+	Workflow string
+	Repo     string
+}
+
+func (e *InvalidClaimError) Error() string {
+	return fmt.Sprintf("ticket %s has invalid workflow claim %q for repo %s", e.Ticket, e.Workflow, e.Repo)
+}
+
+const claimPrefix = "wf:"
+
+// ResolveWorkflow routes a ticket to exactly one workflow following the
+// deterministic routing order: multiple claims are invalid; a single claim
+// resolves directly from repo bindings without re-running filters; an
+// unknown or unbound claim is invalid; otherwise precompiled matchers run —
+// zero matches is ErrNoMatch, one match wins, several is ambiguous.
+func ResolveWorkflow(registered *repo.Repo, ticket task.Ticket) (*workflow.Workflow, error) {
+	claims := ticket.WorkflowClaims
+	if len(claims) > 1 {
+		return nil, &InvalidClaimError{Ticket: ticket.Key, Workflow: strings.Join(claims, ","), Repo: registered.Name}
+	}
+	if len(claims) == 1 {
+		name := strings.TrimPrefix(claims[0], claimPrefix)
+		for _, b := range registered.Workflows {
+			if b.Workflow.Name == name {
+				return b.Workflow, nil
+			}
+		}
+		return nil, &InvalidClaimError{Ticket: ticket.Key, Workflow: name, Repo: registered.Name}
+	}
+	var matched []*workflow.Workflow
+	for _, b := range registered.Workflows {
+		if b.Match != nil && b.Match(ticket) {
+			matched = append(matched, b.Workflow)
+		}
+	}
+	switch len(matched) {
+	case 0:
+		return nil, ErrNoMatch
+	case 1:
+		return matched[0], nil
+	default:
+		names := make([]string, 0, len(matched))
+		for _, wf := range matched {
+			names = append(names, wf.Name)
+		}
+		sort.Strings(names)
+		return nil, &AmbiguousError{Ticket: ticket.Key, Workflows: names}
+	}
+}

package/internal/router/router_test.go

@@ -0,0 +1,144 @@
+package router_test
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/router"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// 3.11: Ticket Router tests (pure) per specs/repo-workflow-routing
+// "Existing workflow claims take precedence" and "Unclaimed routing is
+// unambiguous", following design decision 6's exact routing order.
+
+func wf(name string) *workflow.Workflow {
+	return &workflow.Workflow{
+		Name:  name,
+		Repos: []string{"payments"},
+		Nodes: map[string]workflow.Node{
+			"start": {OnSuccess: []workflow.Route{{Target: "coding"}}},
+			"coding": {
+				Type: workflow.NodeAgent, Agent: "build", Description: "work",
+				OnSuccess: []workflow.Route{{Target: "end"}},
+				OnFailure: []workflow.Route{{Target: "coding"}},
+			},
+			"end": {},
+		},
+	}
+}
+
+func binding(w *workflow.Workflow, match func(task.Ticket) bool) repo.WorkflowBinding {
+	return repo.WorkflowBinding{Workflow: w, Match: match}
+}
+
+func repoWith(bindings ...repo.WorkflowBinding) *repo.Repo {
+	return &repo.Repo{Name: "payments", Path: "/srv/payments", Workflows: bindings}
+}
+
+func TestMultipleClaimsInvalid(t *testing.T) {
+	r := repoWith(binding(wf("aFlow"), nil), binding(wf("bFlow"), nil))
+	ticket := task.Ticket{Key: "PAY-101", WorkflowClaims: []string{"wf:aFlow", "wf:bFlow"}}
+
+	_, err := router.ResolveWorkflow(r, ticket)
+	var ice *router.InvalidClaimError
+	if !errors.As(err, &ice) {
+		t.Fatalf("err = %v, want InvalidClaimError", err)
+	}
+}
+
+func TestSingleClaimResolvesDirectly(t *testing.T) {
+	// Filters must NOT be re-run for a claimed ticket: the matcher would
+	// reject this ticket, and the claim still wins.
+	matchCalled := false
+	r := repoWith(binding(wf("basicFlow"), func(task.Ticket) bool {
+		matchCalled = true
+		return false
+	}))
+	ticket := task.Ticket{Key: "PAY-101", WorkflowClaims: []string{"wf:basicFlow"}}
+
+	got, err := router.ResolveWorkflow(r, ticket)
+	if err != nil {
+		t.Fatalf("ResolveWorkflow failed: %v", err)
+	}
+	if got.Name != "basicFlow" {
+		t.Fatalf("resolved %q, want basicFlow", got.Name)
+	}
+	if matchCalled {
+		t.Fatal("matcher re-evaluated for a singly claimed ticket; claim resolves directly")
+	}
+}
+
+func TestUnknownClaimInvalid(t *testing.T) {
+	r := repoWith(binding(wf("basicFlow"), nil))
+	ticket := task.Ticket{Key: "PAY-101", WorkflowClaims: []string{"wf:ghost"}}
+
+	_, err := router.ResolveWorkflow(r, ticket)
+	var ice *router.InvalidClaimError
+	if !errors.As(err, &ice) {
+		t.Fatalf("err = %v, want InvalidClaimError for unknown claim", err)
+	}
+}
+
+func TestClaimForWorkflowNotBoundToRepo(t *testing.T) {
+	// otherFlow exists but targets another repo, so it is not in this
+	// repo's bindings.
+	r := repoWith(binding(wf("basicFlow"), nil))
+	ticket := task.Ticket{Key: "PAY-101", WorkflowClaims: []string{"wf:otherFlow"}}
+
+	_, err := router.ResolveWorkflow(r, ticket)
+	var ice *router.InvalidClaimError
+	if !errors.As(err, &ice) {
+		t.Fatalf("err = %v, want InvalidClaimError for unbound claim", err)
+	}
+}
+
+func TestZeroMatchesIgnored(t *testing.T) {
+	r := repoWith(binding(wf("basicFlow"), func(task.Ticket) bool { return false }))
+	ticket := task.Ticket{Key: "PAY-101"}
+
+	_, err := router.ResolveWorkflow(r, ticket)
+	if !errors.Is(err, router.ErrNoMatch) {
+		t.Fatalf("err = %v, want ErrNoMatch", err)
+	}
+}
+
+func TestOneMatchSelected(t *testing.T) {
+	r := repoWith(
+		binding(wf("basicFlow"), func(task.Ticket) bool { return true }),
+		binding(wf("otherFlow"), func(task.Ticket) bool { return false }),
+	)
+	ticket := task.Ticket{Key: "PAY-101"}
+
+	got, err := router.ResolveWorkflow(r, ticket)
+	if err != nil {
+		t.Fatalf("ResolveWorkflow failed: %v", err)
+	}
+	if got.Name != "basicFlow" {
+		t.Fatalf("resolved %q, want basicFlow", got.Name)
+	}
+}
+
+func TestMultipleMatchesAmbiguous(t *testing.T) {
+	r := repoWith(
+		binding(wf("basicFlow"), func(task.Ticket) bool { return true }),
+		binding(wf("otherFlow"), func(task.Ticket) bool { return true }),
+	)
+	ticket := task.Ticket{Key: "PAY-101", WorkflowClaims: nil}
+
+	before := ticket
+	_, err := router.ResolveWorkflow(r, ticket)
+	var amb *router.AmbiguousError
+	if !errors.As(err, &amb) {
+		t.Fatalf("err = %v, want AmbiguousError", err)
+	}
+	if len(amb.Workflows) != 2 {
+		t.Fatalf("AmbiguousError.Workflows = %v, want both workflows", amb.Workflows)
+	}
+	// No mutation on ambiguity.
+	if ticket.WorkflowClaims != nil || ticket.Key != before.Key {
+		t.Fatalf("ticket mutated on ambiguity: %+v", ticket)
+	}
+}

package/internal/run/manager.go

@@ -0,0 +1,108 @@
+package run
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// CancellationMarker is the stable parent comment marker recording that the
+// run was canceled; a missing claimed run carrying it is never recreated.
+func CancellationMarker(id ID) string {
+	return string(id) + ":cancellation"
+}
+
+// RunManager performs only assignment and durable-run creation.
+type RunManager struct {
+	Executor Executor
+	Runs     RunQueries
+	// Gate, when non-nil, is the lifecycle mutex shared with
+	// workflow.Service.Submit/Remove (design.md decision 23): run creation
+	// holds it from final workflow resolution through claim + EnsureRun so
+	// a run never starts against a workflow definition that is concurrently
+	// being replaced or removed. A plain *sync.Mutex — no lock service.
+	Gate *sync.Mutex
+}
+
+// EnsureRun claims the ticket if unassigned, skips claiming when the ticket
+// is already assigned to this workflow, checks the stable cancellation
+// marker before recreating a missing claimed run, then ensures the durable
+// run with a value snapshot of the workflow.
+func (m *RunManager) EnsureRun(ctx context.Context, rp *repo.Repo, wf *workflow.Workflow, ticket task.Ticket) error {
+	if m.Gate != nil {
+		m.Gate.Lock()
+		defer m.Gate.Unlock()
+	}
+	id := identity.NewRunID(rp.Name, wf.Name, ticket.Key)
+	claimed := false
+	for _, c := range ticket.WorkflowClaims {
+		if c == "wf:"+wf.Name {
+			claimed = true
+			break
+		}
+	}
+	if !claimed {
+		if err := rp.TaskSystem.Claim(ctx, ticket.Ref(), wf.Name); err != nil {
+			slog.Info("ensure-run outcome",
+				"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+				"outcome", "error", "stage", "claim", "error", err)
+			return fmt.Errorf("claim %s for workflow %s: %w", ticket.Key, wf.Name, err)
+		}
+	} else {
+		// Claimed but possibly missing its run (claim-before-run crash gap or
+		// retention cleanup): never recreate a canceled run.
+		marked, err := rp.TaskSystem.HasComment(ctx, task.Target{Parent: ticket.Ref()}, CancellationMarker(id))
+		if err != nil {
+			slog.Info("ensure-run outcome",
+				"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+				"outcome", "error", "stage", "cancellation-marker", "error", err)
+			return fmt.Errorf("check cancellation marker on %s: %w", ticket.Key, err)
+		}
+		if marked {
+			slog.Info("ensure-run outcome",
+				"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+				"outcome", "skipped-cancellation-marker")
+			return nil
+		}
+	}
+	created, err := m.Executor.EnsureRun(ctx, Start{
+		ID:       id,
+		Repo:     rp.Name,
+		RepoPath: rp.Path,
+		Workflow: *wf,
+		Ticket:   ticket.Ref(),
+	})
+	if err != nil {
+		slog.Info("ensure-run outcome",
+			"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+			"outcome", "error", "stage", "executor", "error", err)
+		return fmt.Errorf("ensure run %s: %w", id, err)
+	}
+	outcome := "exists"
+	if created {
+		outcome = "created"
+	}
+	slog.Info("ensure-run outcome",
+		"ticket", ticket.Key, "repo", rp.Name, "workflow", wf.Name, "runID", string(id),
+		"outcome", outcome)
+	return nil
+}
+
+// CancelByTicket resolves the active run through FindRunByTicket, then
+// calls Executor.CancelRun.
+func (m *RunManager) CancelByTicket(ctx context.Context, ticket, reason string) error {
+	r, err := m.Runs.FindRunByTicket(ctx, ticket)
+	if err != nil {
+		return fmt.Errorf("find run for ticket %s: %w", ticket, err)
+	}
+	if err := m.Executor.CancelRun(ctx, r.ID, reason); err != nil {
+		return fmt.Errorf("cancel run %s: %w", r.ID, err)
+	}
+	return nil
+}

package/internal/run/run.go

@@ -0,0 +1,140 @@
+// Package run defines run IDs/state, orchestration values, the durable
+// Executor boundary, run queries, and the Run Manager.
+package run
+
+import (
+	"context"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+type ID = identity.RunID
+type NodeVisitID = identity.NodeVisitID
+
+type State string
+
+const (
+	StateStarting  State = "starting"
+	StateRunning   State = "running"
+	StateWaiting   State = "waiting"
+	StateBlocked   State = "blocked"
+	StateCompleted State = "completed"
+	StateCanceling State = "canceling"
+	StateCanceled  State = "canceled"
+)
+
+// Start carries the immutable value snapshot of the accepted workflow for
+// deterministic replay. The interpreter consumes only this snapshot.
+type Start struct {
+	ID       ID                `json:"id"`
+	Repo     string            `json:"repo"`
+	RepoPath string            `json:"repoPath"`
+	Workflow workflow.Workflow `json:"workflow"`
+	Ticket   task.TicketRef    `json:"ticket"`
+	Runtime  RuntimePolicy     `json:"runtime"`
+}
+
+type RuntimePolicy struct {
+	KeepTerminalsAlive bool `json:"keepTerminalsAlive"`
+	KeepSessionsAlive  bool `json:"keepSessionsAlive"`
+}
+
+type Work struct {
+	RunID              ID
+	Repo               string
+	Workflow           string
+	Parent             task.TicketRef
+	WorkflowTaskConfig config.RawValues
+	Runtime            RuntimePolicy
+}
+
+type NodeWork struct {
+	Work
+	Node           string
+	NodeVisitID    NodeVisitID
+	Mailbox        task.Mailbox
+	NodeTaskConfig config.RawValues
+}
+
+type CommentWork struct {
+	// RunID is the enclosing durable run; the comment activity uses it to
+	// attribute its 9.3 transition log lines (ticket/runID/node attrs).
+	RunID  ID
+	Item   task.Target
+	Body   string
+	Marker string
+}
+
+// RetryStatus describes the currently pending durable activity retry without
+// replacing the run's lifecycle state.
+type RetryStatus struct {
+	Attempt     int       `json:"attempt"`
+	LastError   string    `json:"lastError"`
+	NextRetryAt time.Time `json:"nextRetryAt"`
+}
+
+type Run struct {
+	ID                 ID             `json:"id"`
+	Repo               string         `json:"repo"`
+	Workflow           string         `json:"workflow"`
+	Ticket             task.TicketRef `json:"ticket"`
+	State              State          `json:"state"`
+	CurrentNode        string         `json:"currentNode,omitempty"`
+	CurrentNodeVisitID NodeVisitID    `json:"currentNodeVisitId,omitempty"`
+	LastError          string         `json:"lastError,omitempty"`
+	Retry              *RetryStatus   `json:"retry,omitempty"`
+	StartedAt          time.Time      `json:"startedAt"`
+	UpdatedAt          time.Time      `json:"updatedAt"`
+	FinishedAt         *time.Time     `json:"finishedAt,omitempty"`
+}
+
+type ReportRequest struct {
+	RunID    ID              `json:"runId"`
+	Node     string          `json:"node"`
+	ReportID string          `json:"reportId"`
+	Report   workflow.Report `json:"report"`
+}
+
+type ReportAck struct {
+	Accepted  bool `json:"accepted"`
+	Duplicate bool `json:"duplicate"`
+}
+
+// NodeRuntimeRegistration binds the OpenCode session emitted for one run/node.
+type NodeRuntimeRegistration struct {
+	RunID     ID     `json:"runId"`
+	Node      string `json:"node"`
+	SessionID string `json:"sessionId"`
+}
+
+type NodeRuntimeRegistrationAck struct {
+	Accepted bool `json:"accepted"`
+}
+
+type Filter struct {
+	Repo     string
+	Workflow string
+	Ticket   string
+	Active   *bool
+}
+
+// Executor is the replacement boundary for go-workflows, Temporal, or
+// another durable engine. No go-workflows context, instance, backend,
+// queue, or error crosses this interface.
+type Executor interface {
+	EnsureRun(ctx context.Context, start Start) (created bool, err error)
+	SubmitReport(ctx context.Context, report ReportRequest) (ReportAck, error)
+	CancelRun(ctx context.Context, id ID, reason string) error
+}
+
+type RunQueries interface {
+	GetRun(ctx context.Context, id ID) (Run, error)
+	FindRunByTicket(ctx context.Context, ticket string) (Run, error)
+	ListRuns(ctx context.Context, filter Filter) ([]Run, error)
+	HasActiveWorkflow(ctx context.Context, workflow string) (bool, error)
+	HasActiveRepo(ctx context.Context, repo string) (bool, error)
+}

package/internal/run/run_identity_test.go

@@ -0,0 +1,52 @@
+package run_test
+
+import (
+	"testing"
+
+	"github.com/rajpopat27/relay-flow/internal/identity"
+	"github.com/rajpopat27/relay-flow/internal/run"
+)
+
+// 3.14: run identity per specs/durable-run-execution "Each parent ticket
+// has one durable run" and "Every node entry has a distinct visit identity".
+
+func TestRunIDDeterministic(t *testing.T) {
+	a := identity.NewRunID("payments", "basicFlow", "PAY-101")
+	b := identity.NewRunID("payments", "basicFlow", "PAY-101")
+	if a != b {
+		t.Fatalf("run ID not deterministic: %q vs %q", a, b)
+	}
+	c := identity.NewRunID("payments", "basicFlow", "PAY-102")
+	if a == c {
+		t.Fatal("different tickets produced the same run ID")
+	}
+	d := identity.NewRunID("other", "basicFlow", "PAY-101")
+	if a == d {
+		t.Fatal("different repos produced the same run ID")
+	}
+}
+
+func TestRunIDDelimiterSafe(t *testing.T) {
+	// Components containing delimiters must not collide.
+	a := identity.NewRunID("pay/ments", "basicFlow", "PAY-101")
+	b := identity.NewRunID("pay", "ments/basicFlow", "PAY-101")
+	if a == b {
+		t.Fatalf("delimiter collision: %q == %q", a, b)
+	}
+}
+
+func TestNodeVisitIDsUniquePerEntry(t *testing.T) {
+	first := identity.NewNodeVisitID()
+	second := identity.NewNodeVisitID()
+	if first == second {
+		t.Fatal("two node entries generated the same nodeVisitID")
+	}
+}
+
+// EnsureRun idempotence is covered with the RunManager tests (3.12) using a
+// fake executor: a repeated EnsureRun with the same deterministic ID
+// returns the existing run without restarting. The durable side-effect
+// stability of nodeVisitID across replay is an engine-level behavior tested
+// in internal/execution/goworkflows.
+
+var _ = run.ID("")