feat: Wire Starlark handler registry in services (#717)

* feat: Wire Starlark handler registry in current-account and payment-order services

Add HandlerRegistry initialization with service client handlers in both
current-account and payment-order services, enabling saga scripts to call
real gRPC services instead of mocks.

Current-account service:
- Creates HandlerRegistry populated with position-keeping, financial-accounting,
  and current-account handlers via RegisterStarlarkHandlers
- Handlers adapt Starlark params (map[string]any) to gRPC calls with
  saga metadata propagation (idempotency, correlation, etc.)
- Registry is stored in serviceClients for future SagaExecutor integration

Payment-order service:
- Creates HandlerRegistry with position-keeping, financial-accounting,
  and current-account handlers
- Uses type assertions for clients stored as interfaces
- Registry available for when payment execution sagas migrate to Starlark

This completes the handler wiring per starlark-service-bindings.md PRD.
The Go orchestrators (DepositOrchestrator, PaymentOrchestrator) remain
functional - Starlark migration is a future task.

saga-script-versioning.13

* fix: Downgrade handler registration failures to warnings in payment-order

Handler registration failures are now warnings instead of errors since
the Starlark runner isn't wired yet. This prevents startup failures when
position-keeping is unavailable during the migration period.

Changes:
- Position-keeping client creation failure is now a warning
- Handler registration errors are now warnings (not startup failures)
- Nil check for posKeepingClient before calling RegisterStarlarkHandlers
- Proper defer cleanup only when client is successfully created

The service can now start and operate without Starlark handlers until
the full Starlark migration is complete.

saga-script-versioning.13

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

services/current-account/cmd/main.go

@@ -12,6 +12,7 @@ import (
 
 	pb "github.com/meridianhub/meridian/api/proto/meridian/current_account/v1"
 	"github.com/meridianhub/meridian/services/current-account/adapters/persistence"
+	currentaccountclient "github.com/meridianhub/meridian/services/current-account/client"
 	"github.com/meridianhub/meridian/services/current-account/config"
 	caobservability "github.com/meridianhub/meridian/services/current-account/observability"
 	"github.com/meridianhub/meridian/services/current-account/service"
@@ -22,6 +23,7 @@ import (
 	refdataclient "github.com/meridianhub/meridian/services/reference-data/client"
 	sharedclients "github.com/meridianhub/meridian/shared/pkg/clients"
 	"github.com/meridianhub/meridian/shared/pkg/idempotency"
+	"github.com/meridianhub/meridian/shared/pkg/saga"
 	"github.com/meridianhub/meridian/shared/platform/bootstrap"
 	"github.com/meridianhub/meridian/shared/platform/defaults"
 	"github.com/meridianhub/meridian/shared/platform/env"
@@ -241,6 +243,10 @@ type serviceClients struct {
 	// Health clients bypass the circuit breaker for health checks
 	positionKeepingHealth     grpc_health_v1.HealthClient
 	financialAccountingHealth grpc_health_v1.HealthClient
+	// HandlerRegistry for Starlark saga execution with service client handlers.
+	// This registry contains handlers that call real gRPC services (not mocks).
+	// See PRD: docs/prd/starlark-service-bindings.md
+	handlerRegistry *saga.HandlerRegistry
 	// Cleanup functions for graceful shutdown
 	cleanupFuncs []func()
 }
@@ -441,6 +447,53 @@ func createServiceWithClients(
 		return nil, nil, fmt.Errorf("failed to create service with existing clients: %w", err)
 	}
 
+	// Create Starlark handler registry with service client handlers.
+	// This enables saga scripts to call real services (not mocks).
+	// See PRD: docs/prd/starlark-service-bindings.md
+	handlerRegistry := saga.NewHandlerRegistry()
+
+	// Register handlers from service clients.
+	// Each RegisterStarlarkHandlers function adapts Starlark params (map[string]any)
+	// to gRPC client calls, propagating saga metadata (idempotency, correlation, etc.)
+	if err := poskeepingclient.RegisterStarlarkHandlers(handlerRegistry, posKeepingClient); err != nil {
+		for _, cleanup := range cleanupFuncs {
+			cleanup()
+		}
+		return nil, nil, fmt.Errorf("failed to register position-keeping handlers: %w", err)
+	}
+
+	if err := finacctclient.RegisterStarlarkHandlers(handlerRegistry, finAcctClient); err != nil {
+		for _, cleanup := range cleanupFuncs {
+			cleanup()
+		}
+		return nil, nil, fmt.Errorf("failed to register financial-accounting handlers: %w", err)
+	}
+
+	// Register current-account handlers (for self-referential operations in sagas)
+	// Note: We need a current-account client that connects to this service's gRPC endpoint.
+	// For now, we create one using the same namespace/port configuration.
+	currentAcctClient, currentAcctCleanup, err := currentaccountclient.New(currentaccountclient.Config{
+		ServiceName: currentaccountclient.ServiceName,
+		Namespace:   namespace,
+		Port:        ports.CurrentAccount,
+		Timeout:     defaults.DefaultRPCTimeout,
+		Tracer:      tracer,
+		// No resilience for self-calls - we want fast failure for local issues
+	})
+	if err != nil {
+		// Current-account handlers are optional - service can work without them
+		logger.Warn("failed to create current-account client for Starlark handlers",
+			"error", err)
+	} else {
+		cleanupFuncs = append(cleanupFuncs, currentAcctCleanup)
+		if regErr := currentaccountclient.RegisterStarlarkHandlers(handlerRegistry, currentAcctClient); regErr != nil {
+			logger.Warn("failed to register current-account handlers", "error", regErr)
+		}
+	}
+
+	logger.Info("Starlark handler registry initialized",
+		"registered_handlers", len(handlerRegistry.List()))
+
 	// Create health clients from the underlying gRPC connections
 	// These bypass the circuit breaker to avoid health checks tripping business operation circuit breakers
 	svcClients := &serviceClients{
@@ -451,6 +504,7 @@ func createServiceWithClients(
 		accountResolver:           accountResolver,
 		positionKeepingHealth:     grpc_health_v1.NewHealthClient(posKeepingClient.Conn()),
 		financialAccountingHealth: grpc_health_v1.NewHealthClient(finAcctClient.Conn()),
+		handlerRegistry:           handlerRegistry,
 		cleanupFuncs:              cleanupFuncs,
 	}
 

services/payment-order/cmd/main.go

@@ -33,6 +33,8 @@ import (
 	currentaccountclient "github.com/meridianhub/meridian/services/current-account/client"
 	financialaccountingclient "github.com/meridianhub/meridian/services/financial-accounting/client"
 	internalbankaccountclient "github.com/meridianhub/meridian/services/internal-bank-account/client"
+	positionkeepingclient "github.com/meridianhub/meridian/services/position-keeping/client"
+	"github.com/meridianhub/meridian/shared/pkg/saga"
 )
 
 // Build information set via ldflags during compilation.
@@ -155,6 +157,70 @@ func run(logger *slog.Logger) error {
 	}()
 	idempotencyService := idempotency.NewRedisService(redisClient)
 
+	// Create Starlark handler registry with service client handlers.
+	// This enables saga scripts to call real services (not mocks).
+	// See PRD: docs/prd/starlark-service-bindings.md
+	handlerRegistry := saga.NewHandlerRegistry()
+
+	// Create position-keeping client for Starlark handlers.
+	// Note: payment-order needs position-keeping for payment execution sagas.
+	// This is optional during migration - service can start without it until Starlark is active.
+	posKeepingClient, posKeepingCleanup, err := positionkeepingclient.New(positionkeepingclient.Config{
+		ServiceName: positionkeepingclient.ServiceName,
+		Namespace:   namespace,
+		Port:        ports.PositionKeeping,
+		Timeout:     defaults.DefaultRPCTimeout,
+		Tracer:      tracer,
+		// No circuit breaker for saga handlers - saga has its own retry logic
+	})
+	if err != nil {
+		// Downgrade to warning - Starlark runtime isn't wired yet, service can operate without handlers
+		logger.Warn("position-keeping client unavailable, Starlark handlers not registered",
+			"error", err)
+	} else {
+		defer posKeepingCleanup()
+	}
+
+	// Register handlers from service clients.
+	// Each RegisterStarlarkHandlers function adapts Starlark params (map[string]any)
+	// to gRPC client calls, propagating saga metadata (idempotency, correlation, etc.)
+	//
+	// Note: Type assertions are required because the createXxxClient functions return
+	// interface types (service.XxxClient) but RegisterStarlarkHandlers needs the
+	// concrete *Client type to access the gRPC connection.
+	//
+	// Handler registration failures are warnings (not errors) since Starlark runner
+	// isn't wired yet - service can operate without handlers during migration.
+	if caClient, ok := currentAccountClient.(*currentaccountclient.Client); ok {
+		if err := currentaccountclient.RegisterStarlarkHandlers(handlerRegistry, caClient); err != nil {
+			logger.Warn("failed to register current-account handlers", "error", err)
+		}
+	} else {
+		logger.Warn("current-account client type assertion failed, Starlark handlers not registered")
+	}
+
+	if faClient, ok := financialAccountingClient.(*financialaccountingclient.Client); ok {
+		if err := financialaccountingclient.RegisterStarlarkHandlers(handlerRegistry, faClient); err != nil {
+			logger.Warn("failed to register financial-accounting handlers", "error", err)
+		}
+	} else {
+		logger.Warn("financial-accounting client type assertion failed, Starlark handlers not registered")
+	}
+
+	if posKeepingClient != nil {
+		if err := positionkeepingclient.RegisterStarlarkHandlers(handlerRegistry, posKeepingClient); err != nil {
+			logger.Warn("failed to register position-keeping handlers", "error", err)
+		}
+	}
+
+	logger.Info("Starlark handler registry initialized",
+		"registered_handlers", len(handlerRegistry.List()))
+
+	// Note: handlerRegistry is available for use with StarlarkRunner when
+	// payment execution sagas are migrated from Go orchestrators to Starlark.
+	// See task 13 in saga-script-versioning for migration details.
+	_ = handlerRegistry // TODO: Wire to StarlarkRunner when saga migration completes
+
 	// Create payment order service
 	paymentOrderService, err := service.NewServiceWithConfig(service.Config{
 		Repository:                repo,