feat: rename correspondent to counterparty in internal-account service (#1212)

* feat: rename correspondent terminology to counterparty in internal-account service

Renames all 'correspondent' terminology to 'counterparty' throughout the
internal-account service to use generic, asset-agnostic language:

- Proto: CorrespondentBankDetails -> CounterpartyDetails, CorrespondentType ->
  CounterpartyType, field names updated (bank_id -> counterparty_id, etc.),
  swift_code moved to attributes map<string,string>
- Domain: correspondent.go -> counterparty.go, CorrespondentDetails ->
  CounterpartyDetails with updated accessor methods
- Errors: ErrCorrespondentRequired/NotAllowed -> ErrCounterpartyRequired/NotAllowed
- DB: Atlas migration to rename correspondent_bank_id/name/external_ref ->
  counterparty_id/name/external_ref, drop swift_code column
- All service, persistence, client, test, and doc files updated accordingly

Intentional breaking change: part of the asset-agnostic accounts initiative
(GitHub Issue asset-agnostic-accounts, Task 7) to remove bank-specific terminology.

* fix: capture error return from NewCounterpartyDetails in integration test

golangci-lint checks integration-tagged files that are excluded from normal
compilation, catching that NewCounterpartyDetails returns (T, error) not T.
Also fix gofumpt formatting in mappers_test.go and repository.go.

* fix: apply gofumpt formatting to internal-account service files

Fix alignment whitespace issues flagged by golangci-lint gofmt checker
in domain/internal_account.go, e2e tests, and account_lifecycle example.

* fix: address CodeRabbit review comments on counterparty rename

- Fix VARCHAR widths in test schemas to match migration (counterparty_id
  VARCHAR(50), counterparty_external_ref VARCHAR(100)) in repository_test.go
- Add counterparty_attributes mapping in starlark.go addCounterpartyDetails
  so metadata (e.g. swift_code) is not silently dropped; use sentinel errors
  to satisfy err113 linter
- Fix e2e test 'CLEARING account rejects counterparty details' to actually
  send CounterpartyDetails and assert the error response
- Fix mismatched product type codes in counterparty_account.go example
  (NOSTRO_EUR/VOSTRO_JPY instead of NOSTRO_USD/VOSTRO_USD)

* fix: guard CounterpartyDetails nil dereferences in example file

Use GetCounterpartyDetails() accessor with nil checks before accessing
fields, preventing panics on unexpected server responses. Applies to
all log sites in counterparty_account.go.

---------

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

Author: bjcoombs

api/proto/meridian/internal_account/v1/internal_account.proto

@@ -130,49 +130,44 @@ enum ControlAction {
   CONTROL_ACTION_CLOSE = 3;
 }
 
-// CorrespondentType distinguishes between nostro and vostro relationships.
-enum CorrespondentType {
-  // CORRESPONDENT_TYPE_UNSPECIFIED is the default value and should not be used.
-  CORRESPONDENT_TYPE_UNSPECIFIED = 0;
-  // CORRESPONDENT_TYPE_NOSTRO means our account at the correspondent bank.
-  CORRESPONDENT_TYPE_NOSTRO = 1;
-  // CORRESPONDENT_TYPE_VOSTRO means their account at our bank.
-  CORRESPONDENT_TYPE_VOSTRO = 2;
+// CounterpartyType distinguishes between nostro and vostro relationships.
+enum CounterpartyType {
+  // COUNTERPARTY_TYPE_UNSPECIFIED is the default value and should not be used.
+  COUNTERPARTY_TYPE_UNSPECIFIED = 0;
+  // COUNTERPARTY_TYPE_NOSTRO means our account at the counterparty.
+  COUNTERPARTY_TYPE_NOSTRO = 1;
+  // COUNTERPARTY_TYPE_VOSTRO means their account at our institution.
+  COUNTERPARTY_TYPE_VOSTRO = 2;
 }
 
-// CorrespondentBankDetails contains information about the correspondent bank
+// CounterpartyDetails contains information about the counterparty
 // for NOSTRO and VOSTRO account types.
-message CorrespondentBankDetails {
-  // bank_id is the unique identifier for the correspondent bank.
-  string bank_id = 1 [(buf.validate.field).string = {
+message CounterpartyDetails {
+  // counterparty_id is the unique identifier for the counterparty.
+  string counterparty_id = 1 [(buf.validate.field).string = {
     min_len: 1
     max_len: 100
     pattern: "^[a-zA-Z0-9_-]+$"
   }];
 
-  // bank_name is the display name of the correspondent bank.
-  string bank_name = 2 [(buf.validate.field).string = {
+  // counterparty_name is the display name of the counterparty.
+  string counterparty_name = 2 [(buf.validate.field).string = {
     min_len: 1
     max_len: 255
   }];
 
-  // external_account_ref is the account reference at the correspondent bank.
-  string external_account_ref = 3 [(buf.validate.field).string = {
+  // counterparty_external_ref is the account reference at the counterparty.
+  string counterparty_external_ref = 3 [(buf.validate.field).string = {
     min_len: 1
     max_len: 255
   }];
 
-  // swift_code is the SWIFT/BIC code of the correspondent bank (optional).
-  // Pattern validates BIC8 (8 chars) or BIC11 (11 chars) format.
-  // Empty string is allowed for correspondent banks without SWIFT codes
-  // (e.g., domestic correspondents, emerging market banks).
-  string swift_code = 4 [(buf.validate.field).string = {
-    max_len: 11
-    pattern: "^([A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?)?$"
-  }];
+  // attributes provides extensibility for counterparty-specific metadata.
+  // Product-type-specific fields (e.g., swift_code for banking) should be stored here.
+  map<string, string> attributes = 4;
 
-  // correspondent_type indicates whether this is a NOSTRO or VOSTRO relationship.
-  CorrespondentType correspondent_type = 5 [(buf.validate.field).enum = {
+  // counterparty_type indicates whether this is a NOSTRO or VOSTRO relationship.
+  CounterpartyType counterparty_type = 5 [(buf.validate.field).enum = {
     defined_only: true
     not_in: [0]
   }];
@@ -220,10 +215,10 @@ message InternalAccountFacility {
     pattern: "^[A-Z][A-Z0-9_]*$"
   }];
 
-  // correspondent_details contains correspondent bank information for NOSTRO/VOSTRO accounts.
+  // counterparty_details contains counterparty information for NOSTRO/VOSTRO accounts.
   // Required when account_type is NOSTRO or VOSTRO (enforced at service layer since
   // proto validation cannot express cross-field conditional constraints).
-  CorrespondentBankDetails correspondent_details = 7;
+  CounterpartyDetails counterparty_details = 7;
 
   // description provides additional context about this account's purpose.
   string description = 8 [(buf.validate.field).string.max_len = 1000];
@@ -323,9 +318,9 @@ message InitiateInternalAccountRequest {
     pattern: "^[A-Z][A-Z0-9_]*$"
   }];
 
-  // correspondent_details is required for NOSTRO/VOSTRO account types.
+  // counterparty_details is required for NOSTRO/VOSTRO account types.
   // Cross-field validation enforced at service layer.
-  CorrespondentBankDetails correspondent_details = 5;
+  CounterpartyDetails counterparty_details = 5;
 
   // description provides additional context about this account's purpose.
   string description = 6 [(buf.validate.field).string.max_len = 1000];
@@ -394,8 +389,8 @@ message UpdateInternalAccountRequest {
   // description is the updated description (optional).
   string description = 3 [(buf.validate.field).string.max_len = 1000];
 
-  // correspondent_details updates correspondent information (for NOSTRO/VOSTRO accounts).
-  CorrespondentBankDetails correspondent_details = 4;
+  // counterparty_details updates counterparty information (for NOSTRO/VOSTRO accounts).
+  CounterpartyDetails counterparty_details = 4;
 
   // expected_version for optimistic locking. If provided, update fails if current version differs.
   int32 expected_version = 5 [(buf.validate.field).int32 = {gte: 0}];

services/internal-account/README.md

@@ -11,7 +11,7 @@ triggers:
   - Balance queries for internal accounts
 instructions: |
   InternalAccount manages non-customer accounts used for internal accounting purposes:
-  - Counterparty accounts (nostro/vostro for correspondent banking)
+  - Counterparty accounts (nostro/vostro for counterparty banking)
   - Operational accounts (clearing, suspense, holding, revenue, expense)
   - Multi-asset support (fiat, energy, carbon credits, compute hours)
 
@@ -42,11 +42,11 @@ BIAN-compliant internal account registry microservice for managing counterparty
 ## Purpose
 
 The Internal Account service manages accounts that are not customer-facing but are essential
-for internal accounting and correspondent banking operations:
+for internal accounting and counterparty banking operations:
 
 - **Clearing Accounts**: Settlement and clearing operations during transaction processing
-- **Nostro Accounts**: "Our account at your bank" - accounts held at correspondent banks
-- **Vostro Accounts**: "Your account at our bank" - accounts held by correspondent banks at us
+- **Nostro Accounts**: "Our account at your bank" - accounts held at counterparty banks
+- **Vostro Accounts**: "Your account at our bank" - accounts held by counterparty banks at us
 - **Holding Accounts**: Temporary holding of funds during multi-step processes
 - **Suspense Accounts**: Unidentified or pending transactions awaiting resolution
 - **Revenue Accounts**: Income and revenue tracking for GL integration
@@ -78,12 +78,11 @@ req := &iba.InitiateInternalAccountRequest{
     Name:           "USD Nostro at HSBC London",
     AccountType:    iba.INTERNAL_ACCOUNT_TYPE_NOSTRO,
     InstrumentCode: "USD",
-    CorrespondentDetails: &iba.CorrespondentBankDetails{
-        BankId:             "hsbc-london",
-        BankName:           "HSBC London",
-        ExternalAccountRef: "GB12HSBC12345678901234",
-        SwiftCode:          "HSBCGB2L",
-        CorrespondentType:  iba.CORRESPONDENT_TYPE_NOSTRO,
+    CounterpartyDetails: &iba.CounterpartyDetails{
+        CounterpartyId:          "hsbc-london",
+        CounterpartyName:        "HSBC London",
+        CounterpartyExternalRef: "GB12HSBC12345678901234",
+        CounterpartyType:        iba.COUNTERPARTY_TYPE_NOSTRO,
     },
     Description:    "Primary USD clearing account at HSBC London",
     IdempotencyKey: &common.IdempotencyKey{Key: "create-nostro-001"},
@@ -197,19 +196,19 @@ classDiagram
         +ClearingPurpose ClearingPurpose
         +InternalAccountStatus AccountStatus
         +string InstrumentCode
-        +CorrespondentBankDetails CorrespondentDetails
+        +CounterpartyDetails CounterpartyDetails
         +string Description
         +int32 Version
         +Timestamp CreatedAt
         +Timestamp UpdatedAt
     }
 
-    class CorrespondentBankDetails {
-        +string BankID
-        +string BankName
-        +string ExternalAccountRef
-        +string SwiftCode
-        +CorrespondentType CorrespondentType
+    class CounterpartyDetails {
+        +string CounterpartyID
+        +string CounterpartyName
+        +string CounterpartyExternalRef
+        +map Attributes
+        +CounterpartyType CounterpartyType
     }
 
     class InternalAccountType {
@@ -247,7 +246,7 @@ classDiagram
         CLOSE
     }
 
-    class CorrespondentType {
+    class CounterpartyType {
         <<enumeration>>
         NOSTRO
         VOSTRO
@@ -256,24 +255,24 @@ classDiagram
     InternalAccountFacility --> InternalAccountType
     InternalAccountFacility --> ClearingPurpose
     InternalAccountFacility --> InternalAccountStatus
-    InternalAccountFacility --> CorrespondentBankDetails
-    CorrespondentBankDetails --> CorrespondentType
+    InternalAccountFacility --> CounterpartyDetails
+    CounterpartyDetails --> CounterpartyType
 ```
 
 **Field Notes:**
 
 - `AccountID`: System-generated KSUID (e.g., `2rPxMVkj3tNmqPwT5Wk8Lc4M9xZ`)
 - `AccountCode`: Business-friendly code (e.g., `NOSTRO-USD-HSBC`, `CLR-001`)
 - `InstrumentCode`: References instrument from Reference Data service (e.g., `USD`, `KWH`, `GPU_HOUR`)
-- `CorrespondentDetails`: Required for NOSTRO/VOSTRO accounts, null for others
+- `CounterpartyDetails`: Required for NOSTRO/VOSTRO accounts, null for others
 
 ## Account Types
 
 | Type | Description | Typical Use |
 |------|-------------|-------------|
 | `CLEARING` | Settlement and clearing operations | Interbank settlement, payment clearing |
-| `NOSTRO` | Our account at another bank | Foreign currency holdings, correspondent banking |
-| `VOSTRO` | Their account at our bank | Correspondent accounts for partner banks |
+| `NOSTRO` | Our account at another bank | Foreign currency holdings, counterparty banking |
+| `VOSTRO` | Their account at our bank | Counterparty accounts for partner banks |
 | `HOLDING` | Temporary fund holding | Escrow, pending transfers, batch processing |
 | `SUSPENSE` | Unmatched/pending transactions | Reconciliation, error correction |
 | `REVENUE` | Income tracking | Fee collection, interest income |
@@ -505,7 +504,7 @@ sequenceDiagram
 | `account_type` | Must not be UNSPECIFIED | "account_type must be specified" |
 | `instrument_code` | Pattern: `^[A-Z][A-Z0-9_]*$`, max 32 chars | "instrument_code must match pattern" |
 | `control_action.reason` | Min 10 chars for audit completeness | "reason must be at least 10 characters" |
-| `correspondent_details` | Required for NOSTRO/VOSTRO types | "correspondent_details required for nostro/vostro" |
+| `counterparty_details` | Required for NOSTRO/VOSTRO types | "counterparty details required for nostro/vostro" |
 
 ## Database Schema
 
@@ -526,17 +525,14 @@ erDiagram
         timestamp updated_at
     }
 
-    correspondent_bank_details {
-        uuid id PK
-        uuid internal_account_id FK
-        string bank_id
-        string bank_name
-        string external_account_ref
-        string swift_code "nullable"
-        string correspondent_type "NOSTRO|VOSTRO"
+    counterparty_details {
+        string counterparty_id "nullable"
+        string counterparty_name "nullable"
+        string counterparty_external_ref "nullable"
+        string counterparty_type "NOSTRO|VOSTRO"
     }
 
-    internal_account ||--o| correspondent_bank_details : "has (nostro/vostro only)"
+    internal_account ||--o| counterparty_details : "has (nostro/vostro only)"
 ```
 
 ## Service Dependencies
@@ -639,22 +635,21 @@ client.ControlInternalAccount(ctx, &iba.ControlInternalAccountRequest{
 })
 ```
 
-### Correspondent Banking
+### Counterparty Banking
 
-Nostro and vostro accounts require correspondent bank details:
+Nostro and vostro accounts require counterparty details:
 
 ```go
 // Nostro: Our account at their bank
 nostro := &iba.InitiateInternalAccountRequest{
     AccountCode: "NOSTRO-EUR-DEUTSCHE",
     AccountType: iba.INTERNAL_ACCOUNT_TYPE_NOSTRO,
     InstrumentCode: "EUR",
-    CorrespondentDetails: &iba.CorrespondentBankDetails{
-        BankId:             "deutsche-frankfurt",
-        BankName:           "Deutsche Bank Frankfurt",
-        ExternalAccountRef: "DE89370400440532013000",
-        SwiftCode:          "DEUTDEFF",
-        CorrespondentType:  iba.CORRESPONDENT_TYPE_NOSTRO,
+    CounterpartyDetails: &iba.CounterpartyDetails{
+        CounterpartyId:          "deutsche-frankfurt",
+        CounterpartyName:        "Deutsche Bank Frankfurt",
+        CounterpartyExternalRef: "DE89370400440532013000",
+        CounterpartyType:        iba.COUNTERPARTY_TYPE_NOSTRO,
     },
 }
 
@@ -663,12 +658,11 @@ vostro := &iba.InitiateInternalAccountRequest{
     AccountCode: "VOSTRO-JPY-MUFG",
     AccountType: iba.INTERNAL_ACCOUNT_TYPE_VOSTRO,
     InstrumentCode: "JPY",
-    CorrespondentDetails: &iba.CorrespondentBankDetails{
-        BankId:             "mufg-tokyo",
-        BankName:           "MUFG Bank Tokyo",
-        ExternalAccountRef: "VOSTRO-MUFG-001",
-        SwiftCode:          "BOTKJPJT",
-        CorrespondentType:  iba.CORRESPONDENT_TYPE_VOSTRO,
+    CounterpartyDetails: &iba.CounterpartyDetails{
+        CounterpartyId:          "mufg-tokyo",
+        CounterpartyName:        "MUFG Bank Tokyo",
+        CounterpartyExternalRef: "VOSTRO-MUFG-001",
+        CounterpartyType:        iba.COUNTERPARTY_TYPE_VOSTRO,
     },
 }
 ```

services/internal-account/adapters/persistence/account_entity.go

@@ -51,10 +51,10 @@ type InternalAccountEntity struct {
 	ProductTypeCode    *string `gorm:"column:product_type_code;type:varchar(100)"`
 	ProductTypeVersion *int    `gorm:"column:product_type_version;type:integer"`
 
-	// Correspondent bank details (nullable for non-nostro/vostro accounts)
-	CorrespondentBankID      *string `gorm:"column:correspondent_bank_id;type:varchar(50)"`
-	CorrespondentBankName    *string `gorm:"column:correspondent_bank_name;type:varchar(255)"`
-	CorrespondentExternalRef *string `gorm:"column:correspondent_external_ref;type:varchar(100)"`
+	// Counterparty details (nullable for non-nostro/vostro accounts)
+	CounterpartyID          *string `gorm:"column:counterparty_id;type:varchar(100)"`
+	CounterpartyName        *string `gorm:"column:counterparty_name;type:varchar(255)"`
+	CounterpartyExternalRef *string `gorm:"column:counterparty_external_ref;type:varchar(255)"`
 
 	// Extensible attributes
 	Attributes AttributesJSON `gorm:"column:attributes;type:jsonb;not null;default:'{}'"`

services/internal-account/adapters/persistence/doc.go

@@ -42,7 +42,7 @@
 //
 //   - UUID primary key
 //   - Tenant-scoped unique constraint on account_code
-//   - JSONB storage for correspondent details
+//   - JSONB storage for counterparty details
 //   - Timestamp tracking (created_at, updated_at)
 //   - Version column for optimistic locking
 //