feat: update Starlark saga handlers for instrument-based field names (#1221)

* feat: update Starlark saga handlers for instrument-based field names

Replace currency with instrument_code and account_identification with
external_identifier across saga scripts and handler infrastructure:

- handlers.yaml: add instrument_code param to position_keeping.initiate_log,
  financial_accounting.initiate_booking_log, capture_posting, and
  compensate_posting; keep currency as deprecated alias
- deposit/withdrawal Starlark scripts: external_identifier replaces
  account_identification, instrument_code replaces currency
- reconciliation_adjustment: pass instrument_code directly instead of
  via currency alias
- dividend_distribution: use instrument_code throughout
- stripe_payment_received: accept instrument_code with currency fallback
- saga_handlers.go: accept instrument_code (preferred) or currency
  (deprecated alias) in all financial handlers; add optionalString helper
- deposit/withdrawal orchestrators: pass external_identifier and
  instrument_code in saga RunnerInput
- service_modules.go: propagate instrument_code in compensation params

* fix: normalize instrument_code once after fallback in stripe saga

Addresses CodeRabbit feedback: if both instrument_code and currency are
present but empty, the previous logic left instrument_code blank. Now
normalize once (strip + upper) after reading both fields, then default
to GBP. Remove redundant .upper() calls at each handler invocation.

---------

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

Author: bjcoombs

services/control-plane/internal/stripe/sagas/stripe_payment_received.star

@@ -20,7 +20,8 @@
 #   - tenant_id: string        - The tenant receiving the payment (e.g., "meridian-ops")
 #   - party_id: string         - The customer party identifier
 #   - amount_cents: int        - Payment amount in smallest currency unit (e.g., pence)
-#   - currency: string         - ISO 4217 currency code (e.g., "gbp")
+#   - instrument_code: string  - Instrument code (e.g., "GBP"). Replaces currency field.
+#   - currency: string         - Deprecated: use instrument_code instead. ISO 4217 currency code (e.g., "gbp")
 #   - charge_id: string        - Stripe Charge ID for reconciliation
 #   - payment_intent_id: string - Stripe PaymentIntent ID
 #   - stripe_event_id: string  - Original Stripe event ID for audit trail
@@ -35,7 +36,12 @@ def execute_stripe_payment_received():
     tenant_id = input_data["tenant_id"]
     party_id = input_data["party_id"]
     amount_cents = input_data["amount_cents"]
-    currency = input_data.get("currency", "GBP")
+    # Accept instrument_code (preferred) or currency (deprecated alias).
+    # Normalize once: strip whitespace, uppercase, default to "GBP".
+    instrument_code = input_data.get("instrument_code", "") or input_data.get("currency", "")
+    instrument_code = instrument_code.strip().upper()
+    if instrument_code == "":
+        instrument_code = "GBP"
     charge_id = input_data["charge_id"]
     payment_intent_id = input_data.get("payment_intent_id", "")
     stripe_event_id = input_data.get("stripe_event_id", "")
@@ -54,7 +60,7 @@ def execute_stripe_payment_received():
     debit_result = position_keeping.initiate_log(
         account_id=nostro_account,
         amount=amount,
-        currency=currency.upper(),
+        instrument_code=instrument_code,
         direction="DEBIT",
         description="Stripe payment received: " + charge_id,
         external_reference_id=charge_id,
@@ -66,7 +72,7 @@ def execute_stripe_payment_received():
     credit_result = position_keeping.initiate_log(
         account_id=prepaid_account,
         amount=amount,
-        currency=currency.upper(),
+        instrument_code=instrument_code,
         direction="CREDIT",
         description="Payment from Stripe: " + charge_id,
         external_reference_id=charge_id,
@@ -78,7 +84,7 @@ def execute_stripe_payment_received():
         "party_id": party_id,
         "prepaid_log_id": credit_result["log_id"],
         "amount_cents": amount_cents,
-        "currency": currency,
+        "instrument_code": instrument_code,
         "charge_id": charge_id,
         "payment_intent_id": payment_intent_id,
         "stripe_event_id": stripe_event_id,

services/current-account/service/deposit_orchestrator.go

@@ -180,13 +180,13 @@ func (o *DepositOrchestrator) Orchestrate(ctx context.Context, account domain.Cu
 		SagaExecutionID: uuid.New(),
 		CorrelationID:   correlationUUID,
 		Input: map[string]interface{}{
-			"account_id":             account.AccountID(),
-			"account_identification": account.ExternalIdentifier(),
-			"amount":                 amount.Amount().String(), // Decimal as string
-			"currency":               string(amount.Currency()),
-			"transaction_id":         transactionID,
-			"clearing_account_id":    clearingAccountID,
-			"attributes":             attributes,
+			"account_id":          account.AccountID(),
+			"external_identifier": account.ExternalIdentifier(),
+			"amount":              amount.Amount().String(), // Decimal as string
+			"instrument_code":     account.InstrumentCode(),
+			"transaction_id":      transactionID,
+			"clearing_account_id": clearingAccountID,
+			"attributes":          attributes,
 		},
 	}
 

services/current-account/service/saga_handlers.go

@@ -190,7 +190,8 @@ func decimalToMoneyAmount(amount decimal.Decimal, currency string) *commonpb.Mon
 // Required params:
 //   - account_id: string - The account identifier
 //   - amount: decimal.Decimal - The transaction amount
-//   - currency: string - Currency code (e.g., "GBP")
+//   - instrument_code: string - Instrument code (e.g., "GBP", "kWh"). Replaces currency.
+//   - currency: string - Deprecated: use instrument_code instead.
 //   - direction: string - "DEBIT" or "CREDIT"
 //   - transaction_id: string - The saga transaction ID
 //
@@ -224,9 +225,13 @@ func currentAccountPositionKeepingInitiateLog(ctx *saga.StarlarkContext, params
 		return nil, wrapHandlerError(handlerName, err)
 	}
 
-	currency, err := requireString(params, "currency")
-	if err != nil {
-		return nil, wrapHandlerError(handlerName, err)
+	// Accept instrument_code (preferred) or currency (deprecated alias)
+	currency := optionalString(params, "instrument_code")
+	if currency == "" {
+		currency = optionalString(params, "currency")
+	}
+	if currency == "" {
+		return nil, wrapHandlerError(handlerName, fmt.Errorf("%w: instrument_code", errMissingParameter))
 	}
 
 	direction, err := requireString(params, "direction")
@@ -423,7 +428,8 @@ func currentAccountPositionKeepingCancelLog(ctx *saga.StarlarkContext, params ma
 //
 // Required params:
 //   - account_id: string - The account identifier
-//   - currency: string - Currency code
+//   - instrument_code: string - Instrument code (e.g., "GBP", "kWh"). Replaces currency.
+//   - currency: string - Deprecated: use instrument_code instead.
 //   - transaction_id: string - The saga transaction ID
 //   - transaction_type: string - "WITHDRAWAL" or "DEPOSIT"
 func currentAccountFinAcctInitiateBookingLog(ctx *saga.StarlarkContext, params map[string]any) (any, error) {
@@ -439,9 +445,13 @@ func currentAccountFinAcctInitiateBookingLog(ctx *saga.StarlarkContext, params m
 		return nil, wrapHandlerError(handlerName, err)
 	}
 
-	currency, err := requireString(params, "currency")
-	if err != nil {
-		return nil, wrapHandlerError(handlerName, err)
+	// Accept instrument_code (preferred) or currency (deprecated alias)
+	currency := optionalString(params, "instrument_code")
+	if currency == "" {
+		currency = optionalString(params, "currency")
+	}
+	if currency == "" {
+		return nil, wrapHandlerError(handlerName, fmt.Errorf("%w: instrument_code", errMissingParameter))
 	}
 
 	transactionID, err := requireString(params, "transaction_id")
@@ -496,7 +506,8 @@ func currentAccountFinAcctInitiateBookingLog(ctx *saga.StarlarkContext, params m
 //   - booking_log_id: string - The booking log ID
 //   - account_id: string - The account to post to
 //   - amount: decimal.Decimal - The posting amount
-//   - currency: string - Currency code
+//   - instrument_code: string - Instrument code (e.g., "GBP", "kWh"). Replaces currency.
+//   - currency: string - Deprecated: use instrument_code instead.
 //   - direction: string - "DEBIT" or "CREDIT"
 //   - transaction_id: string - The saga transaction ID
 //   - posting_type: string - "debit" or "credit" (for idempotency key suffix)
@@ -523,9 +534,13 @@ func currentAccountFinAcctCapturePosting(ctx *saga.StarlarkContext, params map[s
 		return nil, wrapHandlerError(handlerName, err)
 	}
 
-	currency, err := requireString(params, "currency")
-	if err != nil {
-		return nil, wrapHandlerError(handlerName, err)
+	// Accept instrument_code (preferred) or currency (deprecated alias)
+	currency := optionalString(params, "instrument_code")
+	if currency == "" {
+		currency = optionalString(params, "currency")
+	}
+	if currency == "" {
+		return nil, wrapHandlerError(handlerName, fmt.Errorf("%w: instrument_code", errMissingParameter))
 	}
 
 	direction, err := requireString(params, "direction")
@@ -657,7 +672,8 @@ func currentAccountFinAcctUpdateBookingLog(ctx *saga.StarlarkContext, params map
 //   - booking_log_id: string - The booking log ID
 //   - account_id: string - The account to post to
 //   - amount: decimal.Decimal - The posting amount
-//   - currency: string - Currency code
+//   - instrument_code: string - Instrument code (e.g., "GBP", "kWh"). Replaces currency.
+//   - currency: string - Deprecated: use instrument_code instead.
 //   - direction: string - "DEBIT" or "CREDIT" (opposite of original)
 //   - transaction_id: string - The saga transaction ID
 //   - posting_type: string - "debit" or "credit" (original posting type being compensated)
@@ -684,9 +700,13 @@ func currentAccountFinAcctCompensatePosting(ctx *saga.StarlarkContext, params ma
 		return nil, wrapHandlerError(handlerName, err)
 	}
 
-	currency, err := requireString(params, "currency")
-	if err != nil {
-		return nil, wrapHandlerError(handlerName, err)
+	// Accept instrument_code (preferred) or currency (deprecated alias)
+	currency := optionalString(params, "instrument_code")
+	if currency == "" {
+		currency = optionalString(params, "currency")
+	}
+	if currency == "" {
+		return nil, wrapHandlerError(handlerName, fmt.Errorf("%w: instrument_code", errMissingParameter))
 	}
 
 	direction, err := requireString(params, "direction")
@@ -811,6 +831,19 @@ func currentAccountRepositorySave(ctx *saga.StarlarkContext, params map[string]a
 
 // Helper functions for parameter extraction
 
+// optionalString extracts a string parameter, returning empty string if absent or wrong type.
+func optionalString(params map[string]any, key string) string {
+	val, ok := params[key]
+	if !ok || val == nil {
+		return ""
+	}
+	str, ok := val.(string)
+	if !ok {
+		return ""
+	}
+	return str
+}
+
 func requireString(params map[string]any, key string) (string, error) {
 	val, ok := params[key]
 	if !ok {

services/current-account/service/withdrawal_orchestrator.go

@@ -182,13 +182,13 @@ func (o *WithdrawalOrchestrator) Orchestrate(ctx context.Context, account domain
 		SagaExecutionID: uuid.New(),
 		CorrelationID:   correlationUUID,
 		Input: map[string]interface{}{
-			"account_id":             account.AccountID(),
-			"account_identification": account.ExternalIdentifier(),
-			"amount":                 amount.Amount().String(), // Decimal as string
-			"currency":               string(amount.Currency()),
-			"transaction_id":         transactionID,
-			"clearing_account_id":    withdrawalClearingAccountID,
-			"attributes":             attributes,
+			"account_id":          account.AccountID(),
+			"external_identifier": account.ExternalIdentifier(),
+			"amount":              amount.Amount().String(), // Decimal as string
+			"instrument_code":     account.InstrumentCode(),
+			"transaction_id":      transactionID,
+			"clearing_account_id": withdrawalClearingAccountID,
+			"attributes":          attributes,
 		},
 	}
 

services/reference-data/saga/defaults/deposit/v1.0.0.star

@@ -1,7 +1,7 @@
 # Saga: current_account_deposit
 # Version: 1.0.0
 # Previous: none
-# Changed: Migrated from invoke_handler() to typed service modules
+# Changed: Updated field names: account_identification -> external_identifier, currency -> instrument_code
 # Author: Platform Team
 # Date: 2026-01-27
 #
@@ -22,9 +22,9 @@
 #
 # Input data (provided via input_data dictionary):
 #   - account_id: string - Account identifier
-#   - account_identification: string - Account identification for external services
+#   - external_identifier: string - External account identifier (e.g., IBAN)
 #   - amount: string - Decimal amount as string (e.g., "100.50")
-#   - currency: string - Currency code (e.g., "GBP")
+#   - instrument_code: string - Instrument code (e.g., "GBP", "kWh")
 #   - transaction_id: string - Unique transaction identifier
 #   - clearing_account_id: string - Clearing account for double-entry (optional)
 
@@ -35,31 +35,31 @@ deposit_saga = saga(name="current_account_deposit")
 def execute_deposit():
     # Extract input data
     account_id = input_data["account_id"]
-    account_identification = input_data["account_identification"]
+    external_identifier = input_data["external_identifier"]
     amount = Decimal(input_data["amount"])
-    currency = input_data["currency"]
+    instrument_code = input_data["instrument_code"]
     transaction_id = input_data["transaction_id"]
     clearing_account_id = input_data.get("clearing_account_id", "")
-    
+
     # Step 1: Log position in PositionKeeping service with CREDIT direction
     step(name="log_position")
     log_position_result = position_keeping.initiate_log(
-        position_id=account_identification,
+        position_id=external_identifier,
         amount=amount,
-        currency=currency,
+        instrument_code=instrument_code,
         direction="CREDIT",
         transaction_id=transaction_id,
     )
-    
+
     # Step 2: Initiate booking log in FinancialAccounting service
     step(name="initiate_booking_log")
     booking_log_result = financial_accounting.initiate_booking_log(
         account_id=account_id,
-        currency=currency,
+        instrument_code=instrument_code,
         transaction_id=transaction_id,
         transaction_type="DEPOSIT",
     )
-    
+
     # Step 3: Capture DEBIT posting to clearing account (if double-entry enabled)
     # For deposits: DEBIT the clearing account (where funds come from)
     if clearing_account_id != "":
@@ -68,38 +68,38 @@ def execute_deposit():
             booking_log_id=booking_log_result.booking_log_id,
             account_id=clearing_account_id,
             amount=amount,
-            currency=currency,
+            instrument_code=instrument_code,
             direction="DEBIT",
             transaction_id=transaction_id,
             posting_type="debit",
         )
-    
+
     # Step 4: Capture CREDIT posting to customer account
     step(name="capture_credit_posting")
     credit_result = financial_accounting.capture_posting(
         booking_log_id=booking_log_result.booking_log_id,
         account_id=account_id,
         amount=amount,
-        currency=currency,
+        instrument_code=instrument_code,
         direction="CREDIT",
         transaction_id=transaction_id,
         posting_type="credit",
     )
-    
+
     # Step 5: Finalize booking log (transition to POSTED)
     step(name="finalize_booking_log")
     finalize_result = financial_accounting.update_booking_log(
         booking_log_id=booking_log_result.booking_log_id,
         status="POSTED",
     )
-    
+
     # Step 6: Save account metadata
     step(name="save_account")
     save_result = current_account.save(
         account_id=account_id,
         transaction_id=transaction_id,
     )
-    
+
     # Output the saga result
     result = {
         "status": "COMPLETED",

services/reference-data/saga/defaults/dividend_distribution/v1.0.0.star

@@ -21,7 +21,7 @@
 # Input data (provided via input_data dictionary):
 #   - org_id: string - Syndicate organization party ID
 #   - total_amount: string - Total dividend amount as decimal string
-#   - currency: string - Currency code (e.g., "GBP")
+#   - instrument_code: string - Instrument code (e.g., "GBP", "kWh")
 #   - transaction_id: string - Unique transaction identifier
 
 # Define the dividend distribution saga
@@ -31,7 +31,7 @@ def execute_distribution():
     # Extract input data
     org_id = input_data["org_id"]
     total_amount = Decimal(input_data["total_amount"])
-    currency = input_data["currency"]
+    instrument_code = input_data["instrument_code"]
     transaction_id = input_data["transaction_id"]
 
     # Step 1: List all active syndicate participants
@@ -64,7 +64,7 @@ def execute_distribution():
         account_ref = build_org_account_ref(
             party_id=party_id,
             org_id=org_id,
-            currency=currency,
+            instrument_code=instrument_code,
         )
 
         # Resolve the org-scoped account
@@ -75,7 +75,7 @@ def execute_distribution():
         log_result = position_keeping.initiate_log(
             position_id=account_id,
             amount=participant_amount,
-            currency=currency,
+            instrument_code=instrument_code,
             direction="CREDIT",
             transaction_id=transaction_id,
         )

services/reference-data/saga/defaults/reconciliation_adjustment/v1.0.0.star

@@ -51,7 +51,7 @@ def execute_adjustment():
     step(name="initiate_booking")
     booking_result = financial_accounting.initiate_booking_log(
         account_id=account_id,
-        currency=instrument_code,
+        instrument_code=instrument_code,
         transaction_id=transaction_id,
         transaction_type="RECONCILIATION_ADJUSTMENT",
     )
@@ -62,7 +62,7 @@ def execute_adjustment():
         booking_log_id=booking_result.booking_log_id,
         account_id=account_id,
         amount=adjustment_amount,
-        currency=instrument_code,
+        instrument_code=instrument_code,
         direction="DEBIT",
         transaction_id=transaction_id,
         posting_type="debit",
@@ -74,7 +74,7 @@ def execute_adjustment():
         booking_log_id=booking_result.booking_log_id,
         account_id=account_id,
         amount=adjustment_amount,
-        currency=instrument_code,
+        instrument_code=instrument_code,
         direction="CREDIT",
         transaction_id=transaction_id,
         posting_type="credit",