feat: update gRPC service layer for instrument-based quantities (#1217)

* feat: update gRPC service layer for instrument-based quantities

- Map dimension field in toProtoFacility response (grpc_mappers.go)
- Remove dead mapCurrency function and unused currency constants
- Resolve dimension from Reference Data service in InitiateCurrentAccount
- Use NewCurrentAccountWithDimension to persist resolved dimension
- Fall back to CURRENCY dimension when Reference Data unavailable
- Add InstrumentGetter interface and WithInstrumentGetter service option
- Wire Reference Data client as instrument getter in main.go
- Remove dead overdraft fields from saveHandler (grpc_control_endpoints.go)
- Remove TestCurrencyMapping test (mapCurrency no longer exists)

* fix: map registry MONETARY dimension to domain CURRENCY constant

The reference-data registry uses "MONETARY" for currency instruments
while the domain quantity package uses "CURRENCY". Without this mapping,
NewCurrentAccountWithDimension always fails when instrumentGetter is
configured. Add mapRegistryDimension helper and test.

* fix: address CodeRabbit review comments on instrument error handling and metrics

- Distinguish registry.ErrNotFound from transient errors in GetInstrument:
  unknown instrument_code returns codes.InvalidArgument, transient failures
  return codes.Unavailable with external service error metric recorded
- Rename balanceGauge label from "currency" to "instrument_code" to reflect
  the broader instrument model (kWh, GPU_HOUR, GBP, etc.)
- Update all three RecordBalance callers to pass account.InstrumentCode()
  instead of currency string for consistent label values

---------

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

Author: bjcoombs

services/current-account/client/starlark.go

@@ -262,8 +262,6 @@ func terminateLienHandler(client *Client) saga.Handler {
 //
 // Parameters:
 //   - account_id (string): The account identifier to update
-//   - overdraft_limit (decimal): New overdraft limit (optional)
-//   - overdraft_enabled (bool): Enable/disable overdraft (optional)
 //
 // Returns a map containing:
 //   - account_id: The account identifier
@@ -275,30 +273,10 @@ func saveHandler(client *Client) saga.Handler {
 			return nil, err
 		}
 
-		// Build request - all fields are optional except account_id
 		req := &currentaccountv1.UpdateCurrentAccountRequest{
 			AccountId: accountID,
 		}
 
-		// Optional overdraft_limit
-		if overdraftLimitVal, ok := params["overdraft_limit"]; ok {
-			if overdraftLimit, err := saga.RequireDecimalParam(map[string]any{"overdraft_limit": overdraftLimitVal}, "overdraft_limit"); err == nil && !overdraftLimit.IsZero() {
-				// Get currency from params - it should be provided when overdraft_limit is set
-				currency := ""
-				if currencyVal, ok := params["currency"].(string); ok {
-					currency = currencyVal
-				}
-				req.OverdraftLimit = &commonv1.MoneyAmount{
-					Amount: convertDecimalToMoney(overdraftLimit, currency),
-				}
-			}
-		}
-
-		// Optional overdraft_enabled
-		if overdraftEnabled, ok := params["overdraft_enabled"].(bool); ok {
-			req.OverdraftEnabled = &overdraftEnabled
-		}
-
 		clientCtx := prepareClientContext(ctx)
 
 		resp, err := client.UpdateCurrentAccount(clientCtx, req)

services/current-account/cmd/main.go

@@ -570,6 +570,12 @@ func createServiceWithClients(
 		return nil, nil, fmt.Errorf("failed to create service with existing clients: %w", err)
 	}
 
+	// Apply optional service features that use the functional options pattern.
+	if refDataClient != nil {
+		svc.ApplyOptions(service.WithInstrumentGetter(refDataClient))
+		logger.Info("instrument dimension resolution enabled via Reference Data service")
+	}
+
 	// 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

services/current-account/observability/metrics.go

@@ -41,7 +41,7 @@ var (
 			Name: "current_account_balance_cents",
 			Help: "Current account balance in cents",
 		},
-		[]string{"currency"},
+		[]string{"instrument_code"},
 	)
 
 	// Saga metrics
@@ -214,8 +214,8 @@ func RecordWithdrawal(currency string) {
 }
 
 // RecordBalance records the current account balance
-func RecordBalance(balanceCents int64, currency string) {
-	balanceGauge.WithLabelValues(currency).Set(float64(balanceCents))
+func RecordBalance(balanceCents int64, instrumentCode string) {
+	balanceGauge.WithLabelValues(instrumentCode).Set(float64(balanceCents))
 }
 
 // RecordSagaFailure records a saga failure

services/current-account/service/grpc_account_endpoints.go

@@ -15,6 +15,7 @@ import (
 	caobservability "github.com/meridianhub/meridian/services/current-account/observability"
 	"github.com/meridianhub/meridian/services/reference-data/accounttype"
 	celutil "github.com/meridianhub/meridian/services/reference-data/cel"
+	"github.com/meridianhub/meridian/services/reference-data/registry"
 	vf "github.com/meridianhub/meridian/shared/pkg/valuationfeature"
 	"github.com/meridianhub/meridian/shared/platform/tenant"
 	"google.golang.org/grpc/codes"
@@ -37,13 +38,43 @@ func (s *Service) InitiateCurrentAccount(ctx context.Context, req *pb.InitiateCu
 	// Generate account ID
 	accountID := fmt.Sprintf("ACC-%s", uuid.New().String()[:8])
 
-	// Use instrument_code directly as the account's native instrument
-	currency := req.InstrumentCode
-	if currency == "" {
+	// Validate instrument_code is provided
+	instrumentCode := req.InstrumentCode
+	if instrumentCode == "" {
 		operationStatus = operationStatusInvalidCurrency
 		return nil, status.Errorf(codes.InvalidArgument, "instrument_code is required")
 	}
 
+	// Resolve dimension from Reference Data service when available.
+	// Dimension classifies the instrument type (e.g. "CURRENCY", "ENERGY", "COMPUTE").
+	// Falls back to CURRENCY for backward compatibility when the getter is not configured.
+	dimension := "CURRENCY"
+	if s.instrumentGetter != nil {
+		cachedInstrument, err := s.instrumentGetter.GetInstrument(ctx, instrumentCode, 0)
+		if err != nil {
+			if errors.Is(err, registry.ErrNotFound) {
+				// Instrument does not exist in Reference Data - caller supplied an invalid instrument_code
+				operationStatus = "instrument_not_found"
+				s.logger.Warn("instrument not found in Reference Data, cannot create account",
+					"instrument_code", instrumentCode,
+					"account_id", accountID)
+				return nil, status.Errorf(codes.InvalidArgument, "unknown instrument_code: %s", instrumentCode)
+			}
+			// Transient failure (network error, service unavailable, timeout)
+			operationStatus = "instrument_lookup_failed"
+			s.logger.Error("instrument lookup failed due to transient error, cannot create account",
+				"instrument_code", instrumentCode,
+				"account_id", accountID,
+				"error", err)
+			caobservability.RecordExternalServiceError("reference_data", "get_instrument")
+			return nil, status.Errorf(codes.Unavailable, "instrument lookup failed, please retry")
+		}
+		// Map from reference-data registry dimension ("MONETARY") to domain quantity
+		// dimension ("CURRENCY"). The registry uses "MONETARY" while the domain quantity
+		// package uses "CURRENCY" - other dimensions are identical across both packages.
+		dimension = mapRegistryDimension(string(cachedInstrument.Definition.Dimension))
+	}
+
 	// Validate party exists and is active (if party client is configured)
 	if s.partyClient != nil {
 		partyValidationStart := time.Now()
@@ -185,12 +216,13 @@ func (s *Service) InitiateCurrentAccount(ctx context.Context, req *pb.InitiateCu
 			"account_id", accountID)
 	}
 
-	// Create domain model
-	account, err := domain.NewCurrentAccount(
+	// Create domain model with resolved instrument and dimension
+	account, err := domain.NewCurrentAccountWithDimension(
 		accountID,
 		req.ExternalIdentifier,
 		req.PartyId,
-		currency,
+		instrumentCode,
+		dimension,
 		opts...,
 	)
 	if err != nil {
@@ -216,7 +248,7 @@ func (s *Service) InitiateCurrentAccount(ctx context.Context, req *pb.InitiateCu
 	}
 
 	// Record initial balance
-	caobservability.RecordBalance(safeMinorUnits(account.Balance()), currency)
+	caobservability.RecordBalance(safeMinorUnits(account.Balance()), instrumentCode)
 
 	// Convert to proto response
 	return &pb.InitiateCurrentAccountResponse{

services/current-account/service/grpc_deposit_endpoints.go

@@ -202,7 +202,7 @@ func (s *Service) ExecuteDeposit(ctx context.Context, req *pb.ExecuteDepositRequ
 		resp.NewBalance = toMoneyAmount(account.Balance())
 		resp.AvailableBalance = toMoneyAmount(account.AvailableBalance())
 		// Record balance gauge only when we have accurate post-transaction balance
-		caobservability.RecordBalance(safeMinorUnits(account.Balance()), string(account.Balance().Currency()))
+		caobservability.RecordBalance(safeMinorUnits(account.Balance()), account.InstrumentCode())
 	}
 
 	// Store successful result in Redis for future idempotency checks

services/current-account/service/grpc_mappers.go

@@ -10,19 +10,13 @@ import (
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
 
-// Currency code constants
-const (
-	currencyGBP = "GBP"
-	currencyUSD = "USD"
-	currencyEUR = "EUR"
-)
-
 func toProtoFacility(account domain.CurrentAccount) *pb.CurrentAccountFacility {
 	return &pb.CurrentAccountFacility{
 		AccountId:          account.AccountID(),
 		ExternalIdentifier: account.ExternalIdentifier(),
 		AccountStatus:      mapStatusToProto(account.Status()),
 		InstrumentCode:     account.InstrumentCode(),
+		Dimension:          account.Dimension(),
 		CreatedAt:          timestamppb.New(account.CreatedAt()),
 		UpdatedAt:          timestamppb.New(account.UpdatedAt()),
 		// #nosec G115 - Version is bounded by database constraints
@@ -107,6 +101,18 @@ func mapWithdrawalStatusToProto(status domain.WithdrawalStatus) pb.WithdrawalSta
 	}
 }
 
+// mapRegistryDimension converts a reference-data registry dimension string to the
+// domain quantity dimension string used by the current-account service.
+//
+// The reference-data registry uses "MONETARY" for currency instruments, while the
+// domain quantity package uses "CURRENCY". All other dimension values are identical.
+func mapRegistryDimension(registryDimension string) string {
+	if registryDimension == "MONETARY" {
+		return "CURRENCY"
+	}
+	return registryDimension
+}
+
 func mapStatusToProto(status domain.AccountStatus) pb.AccountStatus {
 	switch status {
 	case domain.AccountStatusActive:
@@ -119,24 +125,3 @@ func mapStatusToProto(status domain.AccountStatus) pb.AccountStatus {
 		return pb.AccountStatus_ACCOUNT_STATUS_UNSPECIFIED
 	}
 }
-
-func mapCurrency(currency commonpb.Currency) string {
-	switch currency {
-	case commonpb.Currency_CURRENCY_GBP:
-		return currencyGBP
-	case commonpb.Currency_CURRENCY_USD:
-		return currencyUSD
-	case commonpb.Currency_CURRENCY_EUR:
-		return currencyEUR
-	case commonpb.Currency_CURRENCY_UNSPECIFIED,
-		commonpb.Currency_CURRENCY_JPY,
-		commonpb.Currency_CURRENCY_CHF,
-		commonpb.Currency_CURRENCY_CAD,
-		commonpb.Currency_CURRENCY_AUD:
-		// Return empty string for unsupported currencies
-		// Caller should validate and return error
-		return ""
-	default:
-		return ""
-	}
-}

services/current-account/service/grpc_service.go

@@ -143,6 +143,15 @@ type AccountTypeCache interface {
 // Option is a functional option for configuring optional Service dependencies.
 type Option func(*Service)
 
+// WithInstrumentGetter sets the instrument getter for dimension resolution from Reference Data.
+// When set, the service resolves the account dimension from the instrument_code during account creation.
+// When nil, dimension defaults to CURRENCY (backward-compatible behavior).
+func WithInstrumentGetter(getter InstrumentGetter) Option {
+	return func(s *Service) {
+		s.instrumentGetter = getter
+	}
+}
+
 // WithAccountTypeCache sets the account type cache for product type resolution.
 func WithAccountTypeCache(cache AccountTypeCache) Option {
 	return func(s *Service) {
@@ -198,6 +207,7 @@ type Service struct {
 	posKeepingClient       PositionKeepingClient
 	finAcctClient          FinancialAccountingClient
 	partyClient            PartyClient
+	instrumentGetter       InstrumentGetter // Optional: resolves dimension from instrument_code via Reference Data
 	accountTypeCache       AccountTypeCache // Optional: resolves product type definitions
 	valuationEngine        ValuationEngine  // Optional: executes valuation method logic
 	accountConfig          *config.AccountConfig

services/current-account/service/grpc_service_test.go

@@ -583,24 +583,25 @@ func TestRetrieveCurrentAccountNotFound(t *testing.T) {
 	}
 }
 
-func TestCurrencyMapping(t *testing.T) {
+func TestMapRegistryDimension(t *testing.T) {
 	tests := []struct {
-		name     string
-		currency commonpb.Currency
+		input    string
 		expected string
 	}{
-		{"GBP", commonpb.Currency_CURRENCY_GBP, "GBP"},
-		{"USD", commonpb.Currency_CURRENCY_USD, "USD"},
-		{"EUR", commonpb.Currency_CURRENCY_EUR, "EUR"},
-		{"Unspecified returns empty", commonpb.Currency_CURRENCY_UNSPECIFIED, ""},
-		{"Unsupported JPY returns empty", commonpb.Currency_CURRENCY_JPY, ""},
+		{"MONETARY", "CURRENCY"},
+		{"CURRENCY", "CURRENCY"},
+		{"ENERGY", "ENERGY"},
+		{"COMPUTE", "COMPUTE"},
+		{"MASS", "MASS"},
+		{"VOLUME", "VOLUME"},
+		{"TIME", "TIME"},
+		{"", ""},
 	}
-
 	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result := mapCurrency(tt.currency)
+		t.Run(tt.input, func(t *testing.T) {
+			result := mapRegistryDimension(tt.input)
 			if result != tt.expected {
-				t.Errorf("Expected %s, got %s", tt.expected, result)
+				t.Errorf("mapRegistryDimension(%q) = %q, want %q", tt.input, result, tt.expected)
 			}
 		})
 	}

services/current-account/service/grpc_withdrawal_execute.go

@@ -301,7 +301,7 @@ func (s *Service) ExecuteWithdrawal(ctx context.Context, req *pb.ExecuteWithdraw
 		resp.NewBalance = toMoneyAmount(account.Balance())
 		resp.AvailableBalance = toMoneyAmount(account.AvailableBalance())
 		// Record balance gauge only when we have accurate post-transaction balance
-		caobservability.RecordBalance(safeMinorUnits(account.Balance()), string(account.Balance().Currency()))
+		caobservability.RecordBalance(safeMinorUnits(account.Balance()), account.InstrumentCode())
 	}
 
 	// Mark pending withdrawal as completed (if executing a pending withdrawal)