Feat v0.9.9 surface access roles (#83)

Co-authored-by: Jeffrey Smith <jasafpro@gmail.com>
Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>

CHANGELOG.md

@@ -2,6 +2,57 @@
 
 All notable changes to Armature are documented here.
 
+## v0.9.9 — Surface Access via Roles
+
+Surfaces can now gate access by team role. A manifest declaring
+`"access": "role:approver"` restricts the surface to users who hold the
+`approver` role in any team — consistent with how `group:NAME` works.
+
+**New surface access level: `role:ROLENAME`**
+
+- Added to both `evaluateAccess()` and `validAccessLevels()` validation
+- User must hold the specified role in at least one team (any-team
+  semantics — no team context needed in the URL)
+- System admins bypass role checks, consistent with `RequireRole`
+  middleware
+- Unauthenticated users get redirected to login
+- Graceful fallback: if Teams store is nil, access is denied (fail closed)
+
+**New store method: `HasRoleInAnyTeam(ctx, userID, role)`**
+
+- Checks both primary role (`team_members`) and additional roles
+  (`team_user_roles`) across all teams in a single query
+- Implemented for both SQLite and PostgreSQL
+
+**Refactor:** `evaluateAccess` promoted from package-level function to
+`Engine` method to enable store access for role lookups.
+
+**Tests:** 10 new tests — 5 handler integration tests (granted, denied,
+unauthenticated, admin bypass, nil store), 3 store tests
+(primary role, additional role, no match), 2 validation tests
+(valid role, empty role name)
+
+## v0.9.8 — Conditional Routing → SDK Primitive
+
+Promotes the workflow branch-rule engine to a generic Starlark SDK
+module available to all extensions — no permission required.
+
+**New Starlark module: `routing`**
+
+- `routing.evaluate(rules, data)` — evaluates an ordered list of
+  condition rules against a data dict; returns the first matching
+  rule's `target` string, or `None` if no rule matches
+- 10 operators: `exists`, `not_exists`, `eq`, `neq`, `gt`, `lt`,
+  `gte`, `lte`, `in`, `contains`
+- First-match-wins semantics
+- Domain-agnostic: uses `target` (not `target_stage`) so any
+  extension can use it for feature flags, content routing, approval
+  logic, etc.
+- Always available — pure computation, no I/O, no permission gate
+
+**Tests:** 8 new unit tests covering all operators, type coercion,
+first-match-wins, empty/missing/bad input
+
 ## v0.9.7 — Full Read/Write Workflow Starlark Module
 
 Extensions with `workflow.access` permission can now start, advance,

ROADMAP.md

@@ -137,16 +137,21 @@ circular import. Four write builtins added: `workflow.start()`,
 `instanceToDict` and `signoffToDict` helpers shared by read+write paths.
 6 new tests.
 
-**v0.9.8 — Conditional Routing → SDK Primitive**
+**v0.9.8 — Conditional Routing → SDK Primitive** *(completed)*
 
-Expose `routing.evaluate(rules, data)` as a Starlark SDK function.
+`routing.evaluate(rules, data)` Starlark builtin — a generic decision
-Branch rules become a reusable decision engine for any extension.
+engine reusable by any extension. 10 operators (exists, not_exists, eq,
+neq, gt, lt, gte, lte, in, contains), first-match-wins, returns target
+string or None. Always available (pure computation, no permission).
+8 new tests.
 
-**v0.9.9 — Surface Access via Roles**
+**v0.9.9 — Surface Access via Roles** *(completed)*
 
-Wire team roles (v0.9.3) into surface access declarations:
+`role:ROLENAME` surface access level. User must hold the role in any
-`access: role:approver`. Kernel middleware checks role membership.
+team (any-team semantics, no URL context needed). `evaluateAccess`
-Completes the workflow→package access story.
+promoted to Engine method for store access. `HasRoleInAnyTeam` store
+method queries both primary and additional roles. Admin bypass, fail-
+closed on nil store. 10 new tests.
 
 ---
 

VERSION

@@ -1 +1 @@
-0.9.7
+0.9.9

docs/STARLARK-REFERENCE.md

@@ -84,6 +84,24 @@ Returns `True` if the user has the permission, `False` otherwise (including
 when the user is not found). Resolves the user's groups and merges granted
 permissions — works for both kernel and extension-declared permissions.
 
+### routing
+
+Generic rule-based decision engine. Evaluates an ordered list of conditions
+against a data dict, returning the first matching rule's target string.
+
+```python
+result = routing.evaluate([
+    {"field": "priority", "op": "eq",  "value": "critical", "target": "escalation"},
+    {"field": "amount",   "op": "gt",  "value": 10000,      "target": "manager_review"},
+    {"field": "region",   "op": "in",  "value": ["EU", "UK"], "target": "gdpr_flow"},
+], stage_data)
+# Returns "escalation", "manager_review", "gdpr_flow", or None
+```
+
+Each rule is a dict with `field`, `op`, `value`, and `target`. Operators:
+`exists`, `not_exists`, `eq`, `neq`, `gt`, `lt`, `gte`, `lte`, `in`,
+`contains`. First-match-wins; returns `None` if no rule matches.
+
 ## Permission-gated modules
 
 These modules are only available if the package has the corresponding

server/handlers/package_validate.go

@@ -259,6 +259,8 @@ func validAccessLevels(access string) bool {
 		return true
 	case strings.HasPrefix(access, "group:"):
 		return strings.TrimPrefix(access, "group:") != ""
+	case strings.HasPrefix(access, "role:"):
+		return strings.TrimPrefix(access, "role:") != ""
 	default:
 		return false
 	}

server/handlers/team_roles_test.go

@@ -262,6 +262,93 @@ func TestRequireRole_Denied(t *testing.T) {
 	}
 }
 
+// ── Store: HasRoleInAnyTeam ──────────────────
+
+func TestHasRoleInAnyTeam_PrimaryRole(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	_, userID, _ := seedTeamAndMember(t, stores)
+
+	// "member" is the primary role assigned during seedTeamAndMember
+	has, err := stores.Teams.HasRoleInAnyTeam(ctx, userID, "member")
+	if err != nil {
+		t.Fatalf("HasRoleInAnyTeam: %v", err)
+	}
+	if !has {
+		t.Error("expected true for primary role 'member'")
+	}
+}
+
+func TestHasRoleInAnyTeam_AdditionalRole(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	teamID, userID, _ := seedTeamAndMember(t, stores)
+	stores.Teams.AddUserRole(ctx, teamID, userID, "reviewer", userID)
+
+	has, err := stores.Teams.HasRoleInAnyTeam(ctx, userID, "reviewer")
+	if err != nil {
+		t.Fatalf("HasRoleInAnyTeam: %v", err)
+	}
+	if !has {
+		t.Error("expected true for additional role 'reviewer'")
+	}
+}
+
+func TestHasRoleInAnyTeam_NoMatch(t *testing.T) {
+	database.RequireTestDB(t)
+	stores := testStores(t)
+	ctx := context.Background()
+
+	_, userID, _ := seedTeamAndMember(t, stores)
+
+	has, err := stores.Teams.HasRoleInAnyTeam(ctx, userID, "nonexistent")
+	if err != nil {
+		t.Fatalf("HasRoleInAnyTeam: %v", err)
+	}
+	if has {
+		t.Error("expected false for non-existent role")
+	}
+}
+
+// ── Manifest: role access validation ────────
+
+func TestValidateManifest_SurfaceRoleAccess(t *testing.T) {
+	m := map[string]any{
+		"id":    "role-pkg",
+		"title": "Role Gated",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "/", "access": "role:approver"},
+		},
+	}
+	info, err := ValidateManifest(m)
+	if err != nil {
+		t.Fatalf("unexpected error for role:approver access: %v", err)
+	}
+	if !info.HasSurfaces {
+		t.Error("expected HasSurfaces to be true")
+	}
+}
+
+func TestValidateManifest_SurfaceRoleAccessEmpty(t *testing.T) {
+	m := map[string]any{
+		"id":    "role-pkg",
+		"title": "Role Gated",
+		"type":  "surface",
+		"surfaces": []any{
+			map[string]any{"path": "/", "access": "role:"},
+		},
+	}
+	_, err := ValidateManifest(m)
+	if err == nil {
+		t.Fatal("expected error for empty role name 'role:'")
+	}
+}
+
 // ── helpers ──────────────────────────────────
 
 func seedRoleUser(t *testing.T, username, email string) string {

server/pages/pages.go

@@ -522,7 +522,7 @@ func (e *Engine) RenderExtensionSurface() gin.HandlerFunc {
 		}
 
 		// ── Access check ─────────────────────────────────────────
-		if !evaluateAccess(c, surfaceAccess) {
+		if !e.evaluateAccess(c, surfaceAccess) {
 			// Redirect unauthenticated users to login; deny others with 403
 			if c.GetString("user_id") == "" {
 				c.Redirect(http.StatusTemporaryRedirect, e.cfg.BasePath+"/login")
@@ -651,7 +651,7 @@ func aggregateAccess(surfaces []any) string {
 }
 
 // evaluateAccess checks whether the current request meets an access requirement.
-func evaluateAccess(c *gin.Context, access string) bool {
+func (e *Engine) evaluateAccess(c *gin.Context, access string) bool {
 	switch {
 	case access == "public":
 		return true
@@ -672,6 +672,20 @@ func evaluateAccess(c *gin.Context, access string) bool {
 			}
 		}
 		return false
+	case strings.HasPrefix(access, "role:"):
+		role := strings.TrimPrefix(access, "role:")
+		userID := c.GetString("user_id")
+		if userID == "" {
+			return false
+		}
+		if c.GetBool("is_admin") {
+			return true
+		}
+		if e.stores.Teams == nil {
+			return false
+		}
+		has, err := e.stores.Teams.HasRoleInAnyTeam(c.Request.Context(), userID, role)
+		return err == nil && has
 	default:
 		return false
 	}

server/pages/pages_handler_test.go

@@ -11,9 +11,69 @@ import (
 	"github.com/gin-gonic/gin"
 
 	"armature/config"
+	"armature/models"
 	"armature/store"
 )
 
+// ── mock TeamStore ───────────────────────────────────────────
+
+// mockTeamStore implements store.TeamStore with a simple role lookup map.
+// Only HasRoleInAnyTeam is functional; everything else is a no-op stub.
+type mockTeamStore struct {
+	// userRoles maps userID → set of roles they hold in any team
+	userRoles map[string]map[string]bool
+}
+
+func newMockTeamStore() *mockTeamStore {
+	return &mockTeamStore{userRoles: make(map[string]map[string]bool)}
+}
+
+func (m *mockTeamStore) addRole(userID, role string) {
+	if m.userRoles[userID] == nil {
+		m.userRoles[userID] = make(map[string]bool)
+	}
+	m.userRoles[userID][role] = true
+}
+
+func (m *mockTeamStore) HasRoleInAnyTeam(_ context.Context, userID, role string) (bool, error) {
+	if roles, ok := m.userRoles[userID]; ok {
+		return roles[role], nil
+	}
+	return false, nil
+}
+
+// Stubs — not exercised by surface access tests.
+func (m *mockTeamStore) Create(context.Context, *models.Team) error                       { return nil }
+func (m *mockTeamStore) GetByID(context.Context, string) (*models.Team, error)            { return nil, nil }
+func (m *mockTeamStore) Update(context.Context, string, map[string]interface{}) error     { return nil }
+func (m *mockTeamStore) Delete(context.Context, string) error                             { return nil }
+func (m *mockTeamStore) List(context.Context) ([]models.Team, error)                      { return nil, nil }
+func (m *mockTeamStore) ListForUser(context.Context, string) ([]models.Team, error)       { return nil, nil }
+func (m *mockTeamStore) AddMember(context.Context, string, string, string) error          { return nil }
+func (m *mockTeamStore) RemoveMember(context.Context, string, string) error               { return nil }
+func (m *mockTeamStore) UpdateMemberRole(context.Context, string, string, string) error   { return nil }
+func (m *mockTeamStore) ListMembers(context.Context, string) ([]models.TeamMember, error) { return nil, nil }
+func (m *mockTeamStore) GetMember(context.Context, string, string) (*models.TeamMember, error) { return nil, nil }
+func (m *mockTeamStore) GetUserTeamIDs(context.Context, string) ([]string, error)         { return nil, nil }
+func (m *mockTeamStore) IsTeamAdmin(context.Context, string, string) (bool, error)        { return false, nil }
+func (m *mockTeamStore) IsMember(context.Context, string, string) (bool, error)           { return false, nil }
+func (m *mockTeamStore) Exists(context.Context, string) (bool, error)                     { return false, nil }
+func (m *mockTeamStore) UpdateMemberRoleByID(context.Context, string, string, string) (int64, error) { return 0, nil }
+func (m *mockTeamStore) DeleteMemberByID(context.Context, string, string) (int64, error)  { return 0, nil }
+func (m *mockTeamStore) ListTeamAuditActions(context.Context, string) ([]string, error)   { return nil, nil }
+func (m *mockTeamStore) GetFirstTeamIDForUser(context.Context, string) (string, error)    { return "", nil }
+func (m *mockTeamStore) AddMemberReturningID(context.Context, string, string, string) (string, error) { return "", nil }
+func (m *mockTeamStore) MergeSettings(context.Context, string, string) error              { return nil }
+func (m *mockTeamStore) AddUserRole(context.Context, string, string, string, string) error { return nil }
+func (m *mockTeamStore) RemoveUserRole(context.Context, string, string, string) error     { return nil }
+func (m *mockTeamStore) ListUserRoles(context.Context, string, string) ([]string, error)  { return nil, nil }
+func (m *mockTeamStore) GetMemberRoles(context.Context, string, string) ([]string, error) { return nil, nil }
+func (m *mockTeamStore) HasRole(context.Context, string, string, string) (bool, error)    { return false, nil }
+func (m *mockTeamStore) RemoveAllUserRoles(context.Context, string, string) error         { return nil }
+func (m *mockTeamStore) AddRoleToCatalog(context.Context, string, string, string) error   { return nil }
+func (m *mockTeamStore) ListRoleCatalog(context.Context, string) ([]store.TeamRoleCatalogEntry, error) { return nil, nil }
+func (m *mockTeamStore) RemoveRoleCatalogBySource(context.Context, string, string) error  { return nil }
+
 // ── mock PackageStore ────────────────────────────────────────
 
 // mockPackageStore implements store.PackageStore with in-memory data.
@@ -293,3 +353,136 @@ func TestHandler_EarlyAuthShortCircuit(t *testing.T) {
 		t.Errorf("expected redirect to /login, got %s", loc)
 	}
 }
+
+// ── v0.9.9 — role-based surface access ──────────────────────
+
+// testRouterWithTeams builds a router whose Engine has a mock TeamStore.
+// The optAuth middleware also checks X-Admin header to set is_admin.
+func testRouterWithTeams(t *testing.T, teams *mockTeamStore, pkgs ...*store.PackageRegistration) *gin.Engine {
+	t.Helper()
+	gin.SetMode(gin.TestMode)
+	engine := &Engine{
+		cfg:     &config.Config{BasePath: ""},
+		stores:  store.Stores{Packages: newMockPackageStore(pkgs...), Teams: teams},
+		loaders: make(map[string]DataLoaderFunc),
+	}
+	engine.parseTemplates()
+	engine.registerCoreSurfaces()
+
+	r := gin.New()
+	optAuth := func(c *gin.Context) {
+		if uid := c.GetHeader("X-User-ID"); uid != "" {
+			c.Set("user_id", uid)
+			c.Set("role", "user")
+		}
+		if c.GetHeader("X-Admin") == "true" {
+			c.Set("is_admin", true)
+		}
+		c.Next()
+	}
+	apiAuth := func(c *gin.Context) { c.Next() }
+	apiHandler := func(c *gin.Context) { c.JSON(200, gin.H{"ok": true}) }
+	engine.RegisterExtensionRoutes(r.Group(""), optAuth, apiAuth, apiHandler)
+	return r
+}
+
+func TestHandler_RoleAccess_Granted(t *testing.T) {
+	teams := newMockTeamStore()
+	teams.addRole("user-1", "approver")
+
+	pkg := &store.PackageRegistration{
+		ID: "role-pkg", Title: "Role Pkg", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "role:approver", "title": "Approvals"},
+			},
+		},
+	}
+	r := testRouterWithTeams(t, teams, pkg)
+	w := doGet(r, "/s/role-pkg", "X-User-ID", "user-1")
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 for user with role, got %d", w.Code)
+	}
+}
+
+func TestHandler_RoleAccess_Denied(t *testing.T) {
+	teams := newMockTeamStore()
+	// user-2 has no roles
+
+	pkg := &store.PackageRegistration{
+		ID: "role-pkg", Title: "Role Pkg", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "role:approver", "title": "Approvals"},
+			},
+		},
+	}
+	r := testRouterWithTeams(t, teams, pkg)
+	w := doGet(r, "/s/role-pkg", "X-User-ID", "user-2")
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403 for user without role, got %d", w.Code)
+	}
+}
+
+func TestHandler_RoleAccess_Unauthenticated(t *testing.T) {
+	teams := newMockTeamStore()
+
+	pkg := &store.PackageRegistration{
+		ID: "role-pkg", Title: "Role Pkg", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "role:approver", "title": "Approvals"},
+			},
+		},
+	}
+	r := testRouterWithTeams(t, teams, pkg)
+	w := doGet(r, "/s/role-pkg") // no auth
+	if w.Code != http.StatusTemporaryRedirect {
+		t.Errorf("expected 307 redirect, got %d", w.Code)
+	}
+	loc := w.Header().Get("Location")
+	if !strings.Contains(loc, "/login") {
+		t.Errorf("expected redirect to /login, got %s", loc)
+	}
+}
+
+func TestHandler_RoleAccess_AdminBypass(t *testing.T) {
+	teams := newMockTeamStore()
+	// admin-user has no "approver" role but is_admin=true
+
+	pkg := &store.PackageRegistration{
+		ID: "role-pkg", Title: "Role Pkg", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "role:approver", "title": "Approvals"},
+			},
+		},
+	}
+	r := testRouterWithTeams(t, teams, pkg)
+	w := doGet(r, "/s/role-pkg", "X-User-ID", "admin-user", "X-Admin", "true")
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200 for admin bypass, got %d", w.Code)
+	}
+}
+
+func TestHandler_RoleAccess_NilTeamStore(t *testing.T) {
+	// Engine with no team store — role access should deny gracefully
+	pkg := &store.PackageRegistration{
+		ID: "role-pkg", Title: "Role Pkg", Type: "surface", Source: "extension",
+		Enabled: true, Status: "active",
+		Manifest: map[string]any{
+			"surfaces": []any{
+				map[string]any{"path": "/", "access": "role:approver", "title": "Approvals"},
+			},
+		},
+	}
+	r := testRouter(t, pkg) // testRouter uses nil Teams store
+	w := doGet(r, "/s/role-pkg", "X-User-ID", "user-1")
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403 when Teams store is nil, got %d", w.Code)
+	}
+}

server/sandbox/routing_module.go

@@ -0,0 +1,190 @@
+package sandbox
+
+// routing_module.go
+//
+// Starlark routing module — a generic rule-based decision engine.
+// Always available (pure computation, no I/O).
+//
+// Starlark API:
+//   result = routing.evaluate(rules, data)
+//   # result → "target_string" or None
+
+import (
+	"fmt"
+	"strings"
+
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+)
+
+// BuildRoutingModule creates the "routing" Starlark module.
+// No permission required — pure computation.
+func BuildRoutingModule() *starlarkstruct.Module {
+	return MakeModule("routing", starlark.StringDict{
+		"evaluate": starlark.NewBuiltin("routing.evaluate", routingEvaluateBuiltin()),
+	})
+}
+
+// routingRule is the generic equivalent of workflow.Condition.
+// Uses "target" instead of "target_stage" to be domain-agnostic.
+type routingRule struct {
+	Field  string
+	Op     string
+	Value  any
+	Target string
+}
+
+func routingEvaluateBuiltin() func(*starlark.Thread, *starlark.Builtin, starlark.Tuple, []starlark.Tuple) (starlark.Value, error) {
+	return func(_ *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+		var rulesVal, dataVal starlark.Value
+		if err := starlark.UnpackPositionalArgs(b.Name(), args, kwargs, 2, &rulesVal, &dataVal); err != nil {
+			return nil, err
+		}
+
+		// Convert rules list → []routingRule
+		rulesList, ok := rulesVal.(*starlark.List)
+		if !ok {
+			return nil, fmt.Errorf("routing.evaluate: rules must be a list, got %s", rulesVal.Type())
+		}
+
+		rules := make([]routingRule, rulesList.Len())
+		for i := 0; i < rulesList.Len(); i++ {
+			ruleDict, ok := rulesList.Index(i).(*starlark.Dict)
+			if !ok {
+				return nil, fmt.Errorf("routing.evaluate: rules[%d] must be a dict, got %s", i, rulesList.Index(i).Type())
+			}
+			m := DictToMap(ruleDict)
+
+			field, _ := m["field"].(string)
+			op, _ := m["op"].(string)
+			target, _ := m["target"].(string)
+			if field == "" || op == "" || target == "" {
+				return nil, fmt.Errorf("routing.evaluate: rules[%d] must have field, op, and target", i)
+			}
+			rules[i] = routingRule{
+				Field:  field,
+				Op:     op,
+				Value:  m["value"],
+				Target: target,
+			}
+		}
+
+		// Convert data dict → Go map
+		dataDict, ok := dataVal.(*starlark.Dict)
+		if !ok {
+			return nil, fmt.Errorf("routing.evaluate: data must be a dict, got %s", dataVal.Type())
+		}
+		data := DictToMap(dataDict)
+
+		// Evaluate rules — first match wins
+		for _, rule := range rules {
+			if evaluateRoutingCondition(rule, data) {
+				return starlark.String(rule.Target), nil
+			}
+		}
+
+		return starlark.None, nil
+	}
+}
+
+// ── Evaluation helpers (mirrored from workflow/routing.go) ─────────
+//
+// These are pure functions copied from the workflow package to avoid
+// a sandbox → workflow import cycle. The workflow package continues
+// using its own copy for ResolveNextStage.
+
+// evaluateRoutingCondition checks if a single rule matches against data.
+func evaluateRoutingCondition(rule routingRule, data map[string]any) bool {
+	val, exists := data[rule.Field]
+
+	switch rule.Op {
+	case "exists":
+		return exists
+	case "not_exists":
+		return !exists
+	}
+
+	if !exists {
+		return false
+	}
+
+	switch rule.Op {
+	case "eq":
+		return routingCompareEq(val, rule.Value)
+	case "neq":
+		return !routingCompareEq(val, rule.Value)
+	case "gt":
+		return routingCompareNum(val, rule.Value) > 0
+	case "lt":
+		return routingCompareNum(val, rule.Value) < 0
+	case "gte":
+		return routingCompareNum(val, rule.Value) >= 0
+	case "lte":
+		return routingCompareNum(val, rule.Value) <= 0
+	case "in":
+		return routingCompareIn(val, rule.Value)
+	case "contains":
+		return routingCompareContains(val, rule.Value)
+	default:
+		return false
+	}
+}
+
+func routingCompareEq(a, b any) bool {
+	return fmt.Sprintf("%v", a) == fmt.Sprintf("%v", b)
+}
+
+func routingCompareNum(a, b any) int {
+	af := routingToFloat(a)
+	bf := routingToFloat(b)
+	if af == nil || bf == nil {
+		return 0
+	}
+	switch {
+	case *af < *bf:
+		return -1
+	case *af > *bf:
+		return 1
+	default:
+		return 0
+	}
+}
+
+func routingToFloat(v any) *float64 {
+	switch n := v.(type) {
+	case float64:
+		return &n
+	case int:
+		f := float64(n)
+		return &f
+	case int64:
+		f := float64(n)
+		return &f
+	case string:
+		var f float64
+		if _, err := fmt.Sscanf(n, "%f", &f); err == nil {
+			return &f
+		}
+	}
+	return nil
+}
+
+func routingCompareIn(val, list any) bool {
+	arr, ok := list.([]any)
+	if !ok {
+		return false
+	}
+	vs := fmt.Sprintf("%v", val)
+	for _, item := range arr {
+		if fmt.Sprintf("%v", item) == vs {
+			return true
+		}
+	}
+	return false
+}
+
+func routingCompareContains(val, target any) bool {
+	s := fmt.Sprintf("%v", val)
+	t := fmt.Sprintf("%v", target)
+	return strings.Contains(s, t)
+}

server/sandbox/routing_module_test.go

@@ -0,0 +1,162 @@
+package sandbox
+
+import (
+	"testing"
+
+	"go.starlark.net/starlark"
+)
+
+func runRoutingScript(t *testing.T, script string) starlark.StringDict {
+	t.Helper()
+	mod := BuildRoutingModule()
+	predeclared := starlark.StringDict{"routing": mod}
+	globals, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return globals
+}
+
+func runRoutingScriptErr(t *testing.T, script string) error {
+	t.Helper()
+	mod := BuildRoutingModule()
+	predeclared := starlark.StringDict{"routing": mod}
+	_, err := starlark.ExecFile(&starlark.Thread{Name: "test"}, "test.star", script, predeclared)
+	return err
+}
+
+func TestRoutingEvaluate_SingleMatch(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "priority", "op": "eq", "value": "high", "target": "escalation"},
+], {"priority": "high"})
+`)
+	result := globals["result"]
+	if s, ok := result.(starlark.String); !ok || string(s) != "escalation" {
+		t.Fatalf("expected 'escalation', got %v", result)
+	}
+}
+
+func TestRoutingEvaluate_FirstMatchWins(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "amount", "op": "gt", "value": 100, "target": "big"},
+    {"field": "amount", "op": "gt", "value": 50,  "target": "medium"},
+], {"amount": 200})
+`)
+	result := globals["result"]
+	if s, ok := result.(starlark.String); !ok || string(s) != "big" {
+		t.Fatalf("expected 'big', got %v", result)
+	}
+}
+
+func TestRoutingEvaluate_NoMatch(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([
+    {"field": "status", "op": "eq", "value": "done", "target": "finish"},
+], {"status": "pending"})
+`)
+	if globals["result"] != starlark.None {
+		t.Fatalf("expected None, got %v", globals["result"])
+	}
+}
+
+func TestRoutingEvaluate_EmptyRules(t *testing.T) {
+	globals := runRoutingScript(t, `
+result = routing.evaluate([], {"x": 1})
+`)
+	if globals["result"] != starlark.None {
+		t.Fatalf("expected None, got %v", globals["result"])
+	}
+}
+
+func TestRoutingEvaluate_AllOperators(t *testing.T) {
+	globals := runRoutingScript(t, `
+# exists
+r1 = routing.evaluate([{"field": "x", "op": "exists", "value": "", "target": "yes"}], {"x": 1})
+# not_exists
+r2 = routing.evaluate([{"field": "x", "op": "not_exists", "value": "", "target": "yes"}], {"y": 1})
+# eq
+r3 = routing.evaluate([{"field": "s", "op": "eq", "value": "abc", "target": "yes"}], {"s": "abc"})
+# neq
+r4 = routing.evaluate([{"field": "s", "op": "neq", "value": "abc", "target": "yes"}], {"s": "xyz"})
+# gt
+r5 = routing.evaluate([{"field": "n", "op": "gt", "value": 10, "target": "yes"}], {"n": 20})
+# lt
+r6 = routing.evaluate([{"field": "n", "op": "lt", "value": 10, "target": "yes"}], {"n": 5})
+# gte
+r7 = routing.evaluate([{"field": "n", "op": "gte", "value": 10, "target": "yes"}], {"n": 10})
+# lte
+r8 = routing.evaluate([{"field": "n", "op": "lte", "value": 10, "target": "yes"}], {"n": 10})
+# in
+r9 = routing.evaluate([{"field": "s", "op": "in", "value": ["a", "b", "c"], "target": "yes"}], {"s": "b"})
+# contains
+r10 = routing.evaluate([{"field": "s", "op": "contains", "value": "ell", "target": "yes"}], {"s": "hello"})
+`)
+	for _, name := range []string{"r1", "r2", "r3", "r4", "r5", "r6", "r7", "r8", "r9", "r10"} {
+		v := globals[name]
+		if s, ok := v.(starlark.String); !ok || string(s) != "yes" {
+			t.Errorf("%s: expected 'yes', got %v", name, v)
+		}
+	}
+}
+
+func TestRoutingEvaluate_TypeCoercion(t *testing.T) {
+	globals := runRoutingScript(t, `
+# Numeric string vs int
+r1 = routing.evaluate([
+    {"field": "n", "op": "gt", "value": 10, "target": "yes"},
+], {"n": "20"})
+
+# Int equality via string normalization
+r2 = routing.evaluate([
+    {"field": "n", "op": "eq", "value": 42, "target": "yes"},
+], {"n": 42})
+`)
+	for _, name := range []string{"r1", "r2"} {
+		v := globals[name]
+		if s, ok := v.(starlark.String); !ok || string(s) != "yes" {
+			t.Errorf("%s: expected 'yes', got %v", name, v)
+		}
+	}
+}
+
+func TestRoutingEvaluate_BadInput(t *testing.T) {
+	// rules must be a list
+	err1 := runRoutingScriptErr(t, `routing.evaluate("bad", {})`)
+	if err1 == nil {
+		t.Fatal("expected error for non-list rules")
+	}
+
+	// data must be a dict
+	err2 := runRoutingScriptErr(t, `routing.evaluate([], "bad")`)
+	if err2 == nil {
+		t.Fatal("expected error for non-dict data")
+	}
+
+	// rule missing required fields
+	err3 := runRoutingScriptErr(t, `routing.evaluate([{"field": "x"}], {})`)
+	if err3 == nil {
+		t.Fatal("expected error for incomplete rule")
+	}
+}
+
+func TestRoutingEvaluate_MissingFields(t *testing.T) {
+	globals := runRoutingScript(t, `
+# Field not in data — eq should not match
+r1 = routing.evaluate([
+    {"field": "absent", "op": "eq", "value": "x", "target": "bad"},
+], {"other": "y"})
+
+# not_exists matches when field is absent
+r2 = routing.evaluate([
+    {"field": "absent", "op": "not_exists", "value": "", "target": "good"},
+], {"other": "y"})
+`)
+	if globals["r1"] != starlark.None {
+		t.Fatalf("r1: expected None for missing field, got %v", globals["r1"])
+	}
+	if s, ok := globals["r2"].(starlark.String); !ok || string(s) != "good" {
+		t.Fatalf("r2: expected 'good', got %v", globals["r2"])
+	}
+}

server/sandbox/runner.go

@@ -467,6 +467,9 @@ func (r *Runner) buildModulesWithLibCtx(ctx context.Context, packageID string, m
 	// Always available — read-only team role queries
 	modules["teams"] = BuildTeamsModule(ctx, r.stores)
 
+	// Always available — pure-computation routing decision engine
+	modules["routing"] = BuildRoutingModule()
+
 	// Allows any starlark package to load declared library dependencies.
 	if lc != nil {
 		modules["lib"] = BuildLibModule(ctx, r, packageID, rc, lc)

server/store/interfaces.go

@@ -206,6 +206,9 @@ type TeamStore interface {
 	// HasRole checks whether a user holds a specific role (primary or additional).
 	HasRole(ctx context.Context, teamID, userID, role string) (bool, error)
 
+	// HasRoleInAnyTeam checks whether a user holds a specific role in any team.
+	HasRoleInAnyTeam(ctx context.Context, userID, role string) (bool, error)
+
 	// RemoveAllUserRoles deletes all additional roles for a member (cleanup on removal).
 	RemoveAllUserRoles(ctx context.Context, teamID, userID string) error
 

server/store/postgres/team.go

@@ -388,6 +388,17 @@ func (s *TeamStore) HasRole(ctx context.Context, teamID, userID, role string) (b
 	return exists, err
 }
 
+func (s *TeamStore) HasRoleInAnyTeam(ctx context.Context, userID, role string) (bool, error) {
+	var exists bool
+	err := DB.QueryRowContext(ctx, `
+		SELECT EXISTS(
+			SELECT 1 FROM team_members WHERE user_id = $1 AND role = $2
+			UNION ALL
+			SELECT 1 FROM team_user_roles WHERE user_id = $1 AND role = $2
+		)`, userID, role).Scan(&exists)
+	return exists, err
+}
+
 func (s *TeamStore) RemoveAllUserRoles(ctx context.Context, teamID, userID string) error {
 	_, err := DB.ExecContext(ctx,
 		`DELETE FROM team_user_roles WHERE team_id = $1 AND user_id = $2`,

server/store/sqlite/team.go

@@ -395,6 +395,17 @@ func (s *TeamStore) HasRole(ctx context.Context, teamID, userID, role string) (b
 	return count > 0, err
 }
 
+func (s *TeamStore) HasRoleInAnyTeam(ctx context.Context, userID, role string) (bool, error) {
+	var count int
+	err := DB.QueryRowContext(ctx, `
+		SELECT COUNT(*) FROM (
+			SELECT 1 FROM team_members WHERE user_id = ? AND role = ?
+			UNION ALL
+			SELECT 1 FROM team_user_roles WHERE user_id = ? AND role = ?
+		) LIMIT 1`, userID, role, userID, role).Scan(&count)
+	return count > 0, err
+}
+
 func (s *TeamStore) RemoveAllUserRoles(ctx context.Context, teamID, userID string) error {
 	_, err := DB.ExecContext(ctx,
 		`DELETE FROM team_user_roles WHERE team_id = ? AND user_id = ?`,