feat(current-account): add Account Control Operations (UpCR and CoCR) (#424)

* feat(current-account): add proto definitions for UpdateCurrentAccount and ControlCurrentAccount

Implement BIAN Control Record operations for account lifecycle management:
- UpdateCurrentAccountRequest/Response (UpCR) for modifying overdraft settings and status
- ControlCurrentAccountRequest/Response (CoCR) for state transitions (freeze/unfreeze/close)
- ControlAction enum with FREEZE, UNFREEZE, CLOSE actions
- Validation rules: account_id required, overdraft_rate range 0-100
- HTTP annotations: PUT /v1/current-accounts/{account_id} and POST /v1/current-accounts/{account_id}/control

* feat: implement account state machine with strict validation

Add robust state machine enforcement to CurrentAccount domain model:

- Freeze(reason) now requires 10+ char reason, only from ACTIVE status
- Unfreeze() transitions FROZEN -> ACTIVE and clears freeze reason
- Close() validates zero balance (lien check is service-layer concern)
- UpdateOverdraftSettings() validates rate >= 0 before delegation
- StatusChange struct and statusHistory for audit trail tracking
- CLOSED is terminal - no transitions permitted from closed state

State transition diagram documented in code:
  ACTIVE <-> FROZEN -> CLOSED (terminal)

Includes 30+ comprehensive unit tests covering:
- Valid/invalid state transitions for all methods
- Freeze reason validation (empty, short, exact 10 chars)
- Close with non-zero/negative balance validation
- Status history immutability and audit trail
- Builder methods for freeze reason and status history

* feat(current-account): implement UpdateCurrentAccount and ControlCurrentAccount service handlers

Add BIAN Control Record operations for account lifecycle management:

UpdateCurrentAccount (UpCR):
- Updates overdraft settings (limit, rate, enabled status)
- Uses optimistic locking to prevent concurrent modification conflicts
- Returns InvalidArgument for currency mismatch or invalid rates
- Returns FailedPrecondition if account is closed

ControlCurrentAccount (CoCR):
- Implements FREEZE action with required reason (min 10 characters)
- Implements UNFREEZE to restore frozen accounts to active
- Implements CLOSE with validation for zero balance and no active liens
- All transitions use domain layer state machine for consistency
- Returns Aborted on version conflicts for retry

Also adds CountActiveByAccountID to LienRepository to support lien
checking during account close operations.

Note: Kafka event emission and webhook notifications are documented as
TODOs for future implementation (requires Kafka producer integration).

* feat: add status_history audit trail for BIAN Control Record operations

Add database migration and repository support for tracking account status
changes (ACTIVE -> FROZEN -> CLOSED) with full audit trail in JSONB column.

Changes:
- Add migration for status_history JSONB column and freeze_reason
- Add indexes on status (operational queries) and status_history (audit queries)
- Update CurrentAccountEntity with StatusHistoryJSON GORM type
- Enhance repository to persist status_history on state transitions
- Add comprehensive integration tests for lifecycle, concurrent ops, and auditing
- Fix TestExecuteWithdrawal_AccountClosed to comply with zero-balance close rule

The status_history stores each transition with from_status, to_status, reason,
timestamp, and changed_by for regulatory compliance and audit purposes.

* fix: Move Deprecated notice to separate paragraph for gocritic

The gocritic linter requires Deprecated notices to be in a dedicated
paragraph, separated from the rest of the documentation.

* feat: Address CodeRabbit feedback on status audit trail

- Add ChangedBy field to domain.StatusChange struct to preserve audit info
- Update toDomain() to populate ChangedBy from persistence layer
- Change Close() to accept reason parameter for audit trail
- Update all call sites to pass reason (grpc_service, tests)
- Add test for default reason behavior when empty string passed

* docs: Address minor review feedback with documentation clarifications

- Add TODO for Activate() deprecation removal in next major version
- Document time.Now() usage and clock injection consideration
- Clarify ChangedBy field is populated by persistence layer from context

---------

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

Author: bjcoombs

api/proto/meridian/current_account/v1/current_account.proto

@@ -87,6 +87,22 @@ enum LienStatus {
   LIEN_STATUS_TERMINATED = 3;
 }
 
+// ControlAction defines the control operations that can be performed on an account
+// These are BIAN Control Record (CoCR) operations for account lifecycle management
+enum ControlAction {
+  // CONTROL_ACTION_UNSPECIFIED is the default value and should not be used
+  CONTROL_ACTION_UNSPECIFIED = 0;
+  // CONTROL_ACTION_FREEZE temporarily suspends account operations (reversible)
+  // Transitions: ACTIVE → FROZEN
+  CONTROL_ACTION_FREEZE = 1;
+  // CONTROL_ACTION_UNFREEZE restores a frozen account to active status
+  // Transitions: FROZEN → ACTIVE
+  CONTROL_ACTION_UNFREEZE = 2;
+  // CONTROL_ACTION_CLOSE permanently closes the account (irreversible)
+  // Transitions: ACTIVE or FROZEN → CLOSED
+  CONTROL_ACTION_CLOSE = 3;
+}
+
 // CurrentAccountFacility represents a BIAN-compliant current account facility
 // Task 5.1: Define CurrentAccountFacility message with account identification and status management
 message CurrentAccountFacility {
@@ -693,6 +709,79 @@ message RetrieveLienResponse {
   Lien lien = 1 [(buf.validate.field).required = true];
 }
 
+// Request to update a current account facility settings
+// BIAN: Update Control Record (UpCR) - Modify account configuration
+message UpdateCurrentAccountRequest {
+  // account_id is the account to update (required)
+  string account_id = 1 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 100
+    pattern: "^[a-zA-Z0-9_-]+$"
+  }];
+
+  // overdraft_limit is the new maximum overdraft amount (optional)
+  // If provided, updates the overdraft configuration
+  meridian.common.v1.MoneyAmount overdraft_limit = 2;
+
+  // overdraft_enabled controls whether overdraft facility is active (optional)
+  // Use wrapper to distinguish between "not set" and "set to false"
+  optional bool overdraft_enabled = 3;
+
+  // overdraft_rate is the annual percentage rate for overdraft usage (optional)
+  // Must be between 0 and 100 inclusive
+  optional double overdraft_rate = 4 [(buf.validate.field).double = {
+    gte: 0.0
+    lte: 100.0
+  }];
+
+  // status is the new account status (optional)
+  // Note: For status transitions requiring audit trail (freeze/close), use ControlCurrentAccount instead
+  AccountStatus status = 5 [(buf.validate.field).enum = {
+    defined_only: true
+  }];
+}
+
+// Response for updating a current account
+message UpdateCurrentAccountResponse {
+  // facility is the updated account facility with new settings
+  CurrentAccountFacility facility = 1 [(buf.validate.field).required = true];
+
+  // version is the new version number after update (for optimistic locking)
+  int64 version = 2 [(buf.validate.field).int64 = {gte: 0}];
+}
+
+// Request to perform a control action on a current account
+// BIAN: Control Control Record (CoCR) - Account lifecycle state transitions
+message ControlCurrentAccountRequest {
+  // account_id is the account to control (required)
+  string account_id = 1 [(buf.validate.field).string = {
+    min_len: 1
+    max_len: 100
+    pattern: "^[a-zA-Z0-9_-]+$"
+  }];
+
+  // control_action is the action to perform (required)
+  ControlAction control_action = 2 [(buf.validate.field).enum = {
+    defined_only: true
+    not_in: [0] /* Prevent UNSPECIFIED */
+  }];
+
+  // reason is an explanation for the control action (required for FREEZE and CLOSE)
+  // Minimum 10 characters for audit trail completeness
+  string reason = 3 [(buf.validate.field).string = {
+    max_len: 1000
+  }];
+}
+
+// Response for controlling a current account
+message ControlCurrentAccountResponse {
+  // facility is the account facility with updated status
+  CurrentAccountFacility facility = 1 [(buf.validate.field).required = true];
+
+  // action_timestamp is when the control action was executed
+  google.protobuf.Timestamp action_timestamp = 2 [(buf.validate.field).required = true];
+}
+
 // CurrentAccountService provides BIAN-compliant current account operations.
 //
 // Design Notes:
@@ -828,4 +917,32 @@ service CurrentAccountService {
       get: "/v1/liens/{lien_id}"
     };
   }
+
+  // UpdateCurrentAccount modifies account configuration settings.
+  // BIAN: Update Control Record (UpCR) - Updates overdraft settings, status, etc.
+  // Use this for configuration changes; use ControlCurrentAccount for lifecycle transitions.
+  rpc UpdateCurrentAccount(UpdateCurrentAccountRequest) returns (UpdateCurrentAccountResponse) {
+    option (google.api.http) = {
+      put: "/v1/current-accounts/{account_id}"
+      body: "*"
+    };
+  }
+
+  // ControlCurrentAccount performs lifecycle state transitions on an account.
+  // BIAN: Control Control Record (CoCR) - Freeze, Unfreeze, or Close accounts.
+  // All control actions are logged with timestamps and reasons for audit compliance.
+  rpc ControlCurrentAccount(ControlCurrentAccountRequest) returns (ControlCurrentAccountResponse) {
+    option (google.api.http) = {
+      post: "/v1/current-accounts/{account_id}/control"
+      body: "*"
+    };
+    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
+      responses: {
+        key: "200"
+        value: {
+          description: "Control action executed successfully"
+        }
+      }
+    };
+  }
 }

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

@@ -2,11 +2,18 @@
 package persistence
 
 import (
+	"database/sql/driver"
+	"encoding/json"
+	"errors"
+	"fmt"
 	"time"
 
 	"github.com/google/uuid"
 )
 
+// ErrInvalidStatusHistoryScan is returned when scanning an incompatible type into StatusHistoryJSON.
+var ErrInvalidStatusHistoryScan = errors.New("cannot scan into StatusHistoryJSON")
+
 // CurrentAccountEntity represents the database persistence model for current accounts.
 // This entity MUST match the schema defined in migrations/current_account/*.sql
 // The mapping between domain model and entity is handled by toEntity/toDomain functions.
@@ -28,6 +35,11 @@ type CurrentAccountEntity struct {
 	BalanceUpdatedAt      *time.Time `gorm:"column:balance_updated_at"`
 	OpenedAt              *time.Time `gorm:"column:opened_at;index"`
 	ClosedAt              *time.Time `gorm:"column:closed_at;index"`
+	FreezeReason          *string    `gorm:"column:freeze_reason;type:varchar(1000)"` // Reason when account is frozen
+
+	// Status audit trail - JSONB array of status changes
+	// Note: default is handled in code, not database, for GORM AutoMigrate compatibility
+	StatusHistory StatusHistoryJSON `gorm:"column:status_history;type:jsonb;not null"`
 
 	// Optimistic locking
 	Version int64 `gorm:"column:version;not null;default:1"`
@@ -45,3 +57,43 @@ type CurrentAccountEntity struct {
 func (CurrentAccountEntity) TableName() string {
 	return "account"
 }
+
+// StatusHistoryEntry represents a single status change record for audit trail.
+type StatusHistoryEntry struct {
+	FromStatus string    `json:"from_status"`
+	ToStatus   string    `json:"to_status"`
+	Reason     string    `json:"reason"`
+	Timestamp  time.Time `json:"timestamp"`
+	ChangedBy  string    `json:"changed_by"`
+}
+
+// StatusHistoryJSON is a custom type for handling JSONB status_history column.
+type StatusHistoryJSON []StatusHistoryEntry
+
+// Value implements driver.Valuer for database writes.
+func (s StatusHistoryJSON) Value() (driver.Value, error) {
+	if s == nil {
+		return "[]", nil
+	}
+	return json.Marshal(s)
+}
+
+// Scan implements sql.Scanner for database reads.
+func (s *StatusHistoryJSON) Scan(value interface{}) error {
+	if value == nil {
+		*s = StatusHistoryJSON{}
+		return nil
+	}
+
+	var bytes []byte
+	switch v := value.(type) {
+	case []byte:
+		bytes = v
+	case string:
+		bytes = []byte(v)
+	default:
+		return fmt.Errorf("%w: unsupported type %T", ErrInvalidStatusHistoryScan, value)
+	}
+
+	return json.Unmarshal(bytes, s)
+}

services/current-account/adapters/persistence/lien_repository.go

@@ -190,6 +190,27 @@ func (r *LienRepository) Update(lien *domain.Lien) error {
 	return nil
 }
 
+// CountActiveByAccountID returns the count of active non-expired liens for an account.
+// Used to check if an account has any active liens before closing.
+// In multi-org mode, this query is scoped to the organization from context.
+func (r *LienRepository) CountActiveByAccountID(ctx context.Context, accountID uuid.UUID) (int64, error) {
+	var count int64
+	now := time.Now()
+
+	err := r.withTenantTransaction(ctx, func(tx *gorm.DB) error {
+		result := tx.Model(&LienEntity{}).
+			Where("account_id = ? AND status = ? AND (expires_at IS NULL OR expires_at > ?)",
+				accountID, string(domain.LienStatusActive), now).
+			Count(&count)
+		return result.Error
+	})
+	if err != nil {
+		return 0, err
+	}
+
+	return count, nil
+}
+
 // SumActiveAmountByAccountID returns the total amount of active non-expired liens for an account in cents.
 // Returns ErrLienCurrencyInconsistent if liens with different currencies exist (indicates data corruption).
 // Currency validation is enforced at the service layer when creating liens (InitiateLien).

services/current-account/adapters/persistence/repository.go

@@ -159,6 +159,8 @@ func (r *Repository) Save(ctx context.Context, account domain.CurrentAccount) er
 					"balance":            entity.Balance,
 					"available_balance":  entity.AvailableBalance,
 					"status":             entity.Status,
+					"freeze_reason":      entity.FreezeReason,
+					"status_history":     entity.StatusHistory,
 					"overdraft_limit":    entity.OverdraftLimit,
 					"overdraft_rate":     entity.OverdraftRate,
 					"balance_updated_at": entity.BalanceUpdatedAt,
@@ -402,6 +404,26 @@ func toEntity(ctx context.Context, account domain.CurrentAccount) (*CurrentAccou
 
 	balanceUpdatedAt := account.BalanceUpdatedAt()
 
+	// Convert domain StatusHistory to persistence StatusHistoryJSON
+	domainHistory := account.StatusHistory()
+	statusHistory := make(StatusHistoryJSON, len(domainHistory))
+	for i, change := range domainHistory {
+		statusHistory[i] = StatusHistoryEntry{
+			FromStatus: string(change.From),
+			ToStatus:   string(change.To),
+			Reason:     change.Reason,
+			Timestamp:  change.Timestamp,
+			ChangedBy:  auditUser,
+		}
+	}
+
+	// Handle freeze reason - nil if empty
+	var freezeReason *string
+	if account.FreezeReason() != "" {
+		reason := account.FreezeReason()
+		freezeReason = &reason
+	}
+
 	// ToMinorUnitsUnchecked is safe here: domain layer validates amounts before persistence,
 	// so overflow (>92 quadrillion cents) cannot occur for valid accounts
 	return &CurrentAccountEntity{
@@ -417,6 +439,8 @@ func toEntity(ctx context.Context, account domain.CurrentAccount) (*CurrentAccou
 		OverdraftLimit:        account.OverdraftLimit().ToMinorUnitsUnchecked(),
 		OverdraftRate:         account.OverdraftRate(),
 		BalanceUpdatedAt:      &balanceUpdatedAt,
+		FreezeReason:          freezeReason,
+		StatusHistory:         statusHistory,
 		Version:               account.Version(),
 		CreatedAt:             account.CreatedAt(),
 		UpdatedAt:             account.UpdatedAt(),
@@ -453,6 +477,27 @@ func toDomain(entity *CurrentAccountEntity) (domain.CurrentAccount, error) {
 		balanceUpdatedAt = *entity.BalanceUpdatedAt
 	}
 
+	// Convert persistence StatusHistoryJSON to domain StatusHistory
+	var statusHistory []domain.StatusChange
+	if len(entity.StatusHistory) > 0 {
+		statusHistory = make([]domain.StatusChange, len(entity.StatusHistory))
+		for i, entry := range entity.StatusHistory {
+			statusHistory[i] = domain.StatusChange{
+				From:      domain.AccountStatus(entry.FromStatus),
+				To:        domain.AccountStatus(entry.ToStatus),
+				Reason:    entry.Reason,
+				Timestamp: entry.Timestamp,
+				ChangedBy: entry.ChangedBy,
+			}
+		}
+	}
+
+	// Handle freeze reason - empty string if nil
+	freezeReason := ""
+	if entity.FreezeReason != nil {
+		freezeReason = *entity.FreezeReason
+	}
+
 	// Use builder pattern to construct immutable domain model
 	return domain.NewCurrentAccountBuilder().
 		WithID(entity.ID).
@@ -462,6 +507,8 @@ func toDomain(entity *CurrentAccountEntity) (domain.CurrentAccount, error) {
 		WithBalance(balance).
 		WithAvailableBalance(availableBalance).
 		WithStatus(domain.AccountStatus(entity.Status)).
+		WithFreezeReason(freezeReason).
+		WithStatusHistory(statusHistory).
 		WithOverdraftLimit(overdraftLimit).
 		WithOverdraftEnabled(overdraftEnabled).
 		WithOverdraftRate(entity.OverdraftRate).