feat: Enable multi-asset position keeping for kWh support (#1457)

* feat: Enable multi-asset position keeping for non-fiat instruments

Add NewMoneyFromInstrumentCode to accept both ISO 4217 currency codes
(GBP, USD) and non-currency instrument codes (KWH, GPU_HOUR) in
position-keeping. This removes the fiat-only restriction that blocked
kWh meter read deposits.

Changes:
- domain/quantity.go: Add NewMoneyFromInstrumentCode that falls through
  from currency validation to generic instrument creation
- service/initiate.go: Update googleMoneyToDomain to use the new function
- persistence/postgres_repository.go: Update all Money read paths to
  accept non-currency instrument codes via NewMoneyFromInstrumentCode
- cmd/seed-demo/main.go: Enable kWh meter read deposits with
  double-entry posting (CREDIT customer, DEBIT GSP inventory)

* fix: Document CHAR(3) persistence constraint on instrument codes

Address review feedback: add docstring noting that transaction_log_entry
currency column is CHAR(3), so codes must be 3 characters. Replace
GPU_HOUR test case with GAS (3 chars) to avoid implying longer codes
work end-to-end through persistence.

* fix: Update docstring example to use 3-char instrument code

* fix: address review feedback for multi-asset position keeping

- Add banker's rounding in decimalToCents to prevent silent truncation
- Add 3-char length validation for non-currency instrument codes to fail
  fast before CHAR(3) column constraint

* refactor: generalize multi-asset support to be instrument-agnostic

- Replace hardcoded ENERGY dimension with COUNT as generic placeholder
  since the dimension is not persisted and only the code matters
- Broaden test coverage: KWH, CO2, GPU, GAS all tested as first-class
  instrument codes at both domain and service layers
- Add rejection tests for overlength and single-char codes
- Remove kWH-specific naming from tests and docstrings

---------

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

Author: bjcoombs

cmd/seed-demo/main.go

@@ -731,9 +731,14 @@ func seedCustomerBalances(ctx context.Context, client currentaccountv1.CurrentAc
 			return fmt.Errorf("deposit GBP for %s day %d: %w", acct.customerName, day, err)
 		}
 
-		// KWH meter read deposits are skipped for now — position-keeping service
-		// does not yet support non-fiat instrument codes in InitiateLog.
-		// TODO: Enable after multi-asset position keeping is implemented.
+		// KWH meter read deposit — CREDIT customer kWh account, DEBIT GSP inventory account
+		if err := depositIdempotent(ctx, client, acct.kwhAccountID, dailyKWH, "KWH",
+			fmt.Sprintf("Meter read %s: %.2f kWh", date.Format("2006-01-02"), dailyKWH),
+			fmt.Sprintf("METER-%s-%s", acct.partyID, date.Format("20060102")),
+			acct.gspKwhAccountID, // GSP inventory account is the debit (clearing) side
+		); err != nil {
+			return fmt.Errorf("deposit KWH for %s day %d: %w", acct.customerName, day, err)
+		}
 	}
 
 	fmt.Printf("  %s: %.1f kWh consumed, £%.2f billed (30 days)\n", acct.customerName, totalKWH, totalGBP)

services/position-keeping/adapters/persistence/postgres_repository.go

@@ -328,12 +328,12 @@ func (r *PostgresRepository) FindByID(ctx context.Context, logID uuid.UUID) (*do
 
 		log.StatusTracking = &statusTracking
 
-		// Parse opening balance
+		// Parse opening balance (supports both currency and non-currency codes)
 		// Trim spaces since PostgreSQL CHAR(3) may pad with spaces
 		openingBalanceCurrency = strings.TrimSpace(openingBalanceCurrency)
-		openingBalance, err := domain.NewMoney(openingBalanceAmount, domain.Currency(openingBalanceCurrency))
+		openingBalance, err := domain.NewMoneyFromInstrumentCode(openingBalanceAmount, openingBalanceCurrency)
 		if err != nil {
-			return fmt.Errorf("failed to create opening balance Money: %w", err)
+			return fmt.Errorf("failed to create opening balance Money for instrument %q: %w", openingBalanceCurrency, err)
 		}
 		log.OpeningBalance = openingBalance
 		if openingBalanceRecordedAt.Valid {
@@ -819,7 +819,7 @@ func (r *PostgresRepository) insertTransactionLogEntries(ctx context.Context, tx
 	userID := audit.GetUserFromContext(ctx)
 
 	for _, entry := range entries {
-		// Convert decimal amount to cents (int64)
+		// Convert decimal amount to cents (int64) - uses 2 decimal places for all instruments
 		amountCents := decimalToCents(entry.Amount.Amount)
 
 		batch.Queue(query,
@@ -958,11 +958,12 @@ func (r *PostgresRepository) loadTransactionLogEntriesTx(ctx context.Context, tx
 			return fmt.Errorf("failed to scan transaction log entry: %w", err)
 		}
 
-		// Convert cents to decimal and create Money
+		// Convert cents to decimal and create Money (supports both currency and non-currency codes)
 		amount := centsToDecimal(amountCents)
-		money, err := domain.NewMoney(amount, domain.Currency(currency))
+		currency = strings.TrimSpace(currency)
+		money, err := domain.NewMoneyFromInstrumentCode(amount, currency)
 		if err != nil {
-			return fmt.Errorf("failed to create Money value: %w", err)
+			return fmt.Errorf("failed to create Money value for instrument %q: %w", currency, err)
 		}
 		entry.Amount = money
 		entry.Direction = domain.ParsePostingDirection(direction)
@@ -1165,11 +1166,12 @@ func (r *PostgresRepository) loadTransactionLogEntriesBatchTx(ctx context.Contex
 			return fmt.Errorf("failed to scan transaction log entry in batch: %w", err)
 		}
 
-		// Convert cents to decimal and create Money
+		// Convert cents to decimal and create Money (supports both currency and non-currency codes)
 		amount := centsToDecimal(amountCents)
-		money, err := domain.NewMoney(amount, domain.Currency(currency))
+		currency = strings.TrimSpace(currency)
+		money, err := domain.NewMoneyFromInstrumentCode(amount, currency)
 		if err != nil {
-			return fmt.Errorf("failed to create Money value in batch: %w", err)
+			return fmt.Errorf("failed to create Money value for instrument %q in batch: %w", currency, err)
 		}
 		entry.Amount = money
 		entry.Direction = domain.ParsePostingDirection(direction)
@@ -1384,12 +1386,12 @@ func (r *PostgresRepository) scanLogsTx(ctx context.Context, tx pgx.Tx, rows pgx
 
 		log.StatusTracking = &statusTracking
 
-		// Parse opening balance
+		// Parse opening balance (supports both currency and non-currency codes)
 		// Trim spaces since PostgreSQL CHAR(3) may pad with spaces
 		openingBalanceCurrency = strings.TrimSpace(openingBalanceCurrency)
-		openingBalance, err := domain.NewMoney(openingBalanceAmount, domain.Currency(openingBalanceCurrency))
+		openingBalance, err := domain.NewMoneyFromInstrumentCode(openingBalanceAmount, openingBalanceCurrency)
 		if err != nil {
-			return nil, fmt.Errorf("failed to create opening balance Money: %w", err)
+			return nil, fmt.Errorf("failed to create opening balance Money for instrument %q: %w", openingBalanceCurrency, err)
 		}
 		log.OpeningBalance = openingBalance
 		if openingBalanceRecordedAt.Valid {
@@ -1509,7 +1511,7 @@ func openingBalanceCurrencyCode(m domain.Money) string {
 // domain.Currency constants.
 // Example: 123.45 -> 12345 cents
 func decimalToCents(d decimal.Decimal) int64 {
-	cents := d.Mul(decimal.NewFromInt(100))
+	cents := d.Mul(decimal.NewFromInt(100)).RoundBank(0)
 	return cents.IntPart()
 }
 

services/position-keeping/domain/money_test.go

@@ -373,3 +373,152 @@ func TestMoney_ToMinorUnits(t *testing.T) {
 		})
 	}
 }
+
+func TestNewMoneyFromInstrumentCode(t *testing.T) {
+	tests := []struct {
+		name           string
+		amount         decimal.Decimal
+		code           string
+		wantErr        bool
+		expectedCode   string
+		expectedAmount decimal.Decimal
+	}{
+		{
+			name:           "valid currency GBP",
+			amount:         decimal.NewFromFloat(100.50),
+			code:           "GBP",
+			expectedCode:   "GBP",
+			expectedAmount: decimal.NewFromFloat(100.50),
+		},
+		{
+			name:           "valid currency USD",
+			amount:         decimal.NewFromFloat(42.00),
+			code:           "USD",
+			expectedCode:   "USD",
+			expectedAmount: decimal.NewFromFloat(42.00),
+		},
+		{
+			name:           "energy instrument KWH",
+			amount:         decimal.NewFromFloat(8.54),
+			code:           "KWH",
+			expectedCode:   "KWH",
+			expectedAmount: decimal.NewFromFloat(8.54),
+		},
+		{
+			name:           "gas instrument",
+			amount:         decimal.NewFromFloat(1.25),
+			code:           "GAS",
+			expectedCode:   "GAS",
+			expectedAmount: decimal.NewFromFloat(1.25),
+		},
+		{
+			name:           "carbon credit instrument",
+			amount:         decimal.NewFromFloat(50.00),
+			code:           "CO2",
+			expectedCode:   "CO2",
+			expectedAmount: decimal.NewFromFloat(50.00),
+		},
+		{
+			name:           "compute instrument",
+			amount:         decimal.NewFromFloat(3.75),
+			code:           "GPU",
+			expectedCode:   "GPU",
+			expectedAmount: decimal.NewFromFloat(3.75),
+		},
+		{
+			name:    "empty code",
+			amount:  decimal.NewFromInt(100),
+			code:    "",
+			wantErr: true,
+		},
+		{
+			name:    "overlength code rejected",
+			amount:  decimal.NewFromInt(100),
+			code:    "KWHR",
+			wantErr: true,
+		},
+		{
+			name:    "single char code rejected",
+			amount:  decimal.NewFromInt(100),
+			code:    "X",
+			wantErr: true,
+		},
+		{
+			name:           "zero amount with non-currency",
+			amount:         decimal.Zero,
+			code:           "CO2",
+			expectedCode:   "CO2",
+			expectedAmount: decimal.Zero,
+		},
+		{
+			name:           "negative amount with non-currency",
+			amount:         decimal.NewFromFloat(-5.00),
+			code:           "GAS",
+			expectedCode:   "GAS",
+			expectedAmount: decimal.NewFromFloat(-5.00),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			money, err := NewMoneyFromInstrumentCode(tt.amount, tt.code)
+
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("Expected error but got nil")
+				}
+				return
+			}
+
+			if err != nil {
+				t.Fatalf("Unexpected error: %v", err)
+			}
+
+			if money.Instrument.Code != tt.expectedCode {
+				t.Errorf("Expected instrument code %q, got %q", tt.expectedCode, money.Instrument.Code)
+			}
+
+			if !money.Amount.Equal(tt.expectedAmount) {
+				t.Errorf("Expected amount %v, got %v", tt.expectedAmount, money.Amount)
+			}
+		})
+	}
+}
+
+func TestNewMoneyFromInstrumentCode_RoundTrip(t *testing.T) {
+	// Verify that non-currency instruments round-trip through the same paths as fiat
+	instruments := []struct {
+		code   string
+		amount decimal.Decimal
+	}{
+		{"KWH", decimal.NewFromFloat(8.54)},
+		{"CO2", decimal.NewFromFloat(50.00)},
+		{"GPU", decimal.NewFromFloat(3.75)},
+		{"GAS", decimal.NewFromFloat(1.25)},
+	}
+
+	for _, inst := range instruments {
+		t.Run(inst.code, func(t *testing.T) {
+			m, err := NewMoneyFromInstrumentCode(inst.amount, inst.code)
+			if err != nil {
+				t.Fatalf("NewMoneyFromInstrumentCode(%s) error = %v", inst.code, err)
+			}
+
+			if MoneyCurrency(m) != Currency(inst.code) {
+				t.Errorf("MoneyCurrency() = %q, want %q", MoneyCurrency(m), inst.code)
+			}
+
+			if !m.IsPositive() {
+				t.Errorf("Expected positive %s amount", inst.code)
+			}
+
+			zero, err := NewMoneyFromInstrumentCode(decimal.Zero, inst.code)
+			if err != nil {
+				t.Fatalf("NewMoneyFromInstrumentCode(zero, %s) error = %v", inst.code, err)
+			}
+			if !zero.IsZero() {
+				t.Errorf("Expected zero %s amount", inst.code)
+			}
+		})
+	}
+}

services/position-keeping/domain/quantity.go

@@ -12,6 +12,8 @@
 package domain
 
 import (
+	"fmt"
+
 	"github.com/meridianhub/meridian/shared/domain/money"
 	sharedamount "github.com/meridianhub/meridian/shared/pkg/amount"
 	"github.com/meridianhub/meridian/shared/platform/quantity"
@@ -288,6 +290,42 @@ func ParseCurrency(s string) (Currency, error) {
 	return money.ParseCurrency(s)
 }
 
+// NewMoneyFromInstrumentCode creates a Money value from any instrument code (currency or non-currency).
+// For valid ISO 4217 currencies (GBP, USD, etc.), it uses the standard currency path with correct precision.
+// For non-currency instrument codes, it creates a Money value using the code directly, bypassing
+// currency validation. This enables position-keeping to track any registered instrument while
+// reusing the same Money type for persistence and domain logic.
+//
+// Persistence constraint: the transaction_log_entry.currency column is CHAR(3), so codes must be
+// exactly 3 characters to persist correctly.
+func NewMoneyFromInstrumentCode(amount decimal.Decimal, code string) (Money, error) {
+	if code == "" {
+		return Money{}, ErrEmptyCode
+	}
+
+	// Try currency path first (preserves correct precision for fiat)
+	cur := Currency(code)
+	if cur.IsValid() {
+		return NewMoney(amount, cur)
+	}
+
+	// Fail fast: the transaction_log_entry.currency column is CHAR(3), so non-currency
+	// codes must also be exactly 3 characters to persist correctly.
+	if len(code) != 3 {
+		return Money{}, fmt.Errorf("%w: non-currency instrument code %q must be exactly 3 characters for persistence", ErrInvalidCodeFormat, code)
+	}
+
+	// Non-currency instrument: use precision 2 to match the persistence layer's
+	// decimalToCents/centsToDecimal which assumes 2 decimal places for all instruments.
+	// Use COUNT as a dimension-agnostic placeholder; the dimension is not stored in the
+	// transaction_log_entry table and only the code matters for persistence round-trips.
+	inst, err := quantity.NewInstrument(code, 1, "COUNT", 2)
+	if err != nil {
+		return Money{}, err
+	}
+	return quantity.NewMoney(amount, inst), nil
+}
+
 // =============================================================================
 // Money Accessor Functions (backward compatibility helpers)
 // =============================================================================

services/position-keeping/service/initiate.go

@@ -159,6 +159,7 @@ func validateInitiateRequest(req *positionkeepingv1.InitiateFinancialPositionLog
 
 // googleMoneyToDomain converts google.type.Money to domain.Money.
 // This is the shared conversion logic for all proto-to-domain money conversions.
+// Accepts both ISO 4217 currency codes (GBP, USD) and non-currency instrument codes (KWH, GAS).
 func googleMoneyToDomain(m *money.Money) (domain.Money, error) {
 	if m == nil {
 		return domain.Money{}, nil
@@ -169,7 +170,7 @@ func googleMoneyToDomain(m *money.Money) (domain.Money, error) {
 	nanos := decimal.NewFromInt(int64(m.Nanos)).Div(decimal.NewFromInt(1_000_000_000))
 	totalAmount := amount.Add(nanos)
 
-	return domain.NewMoney(totalAmount, domain.Currency(m.CurrencyCode))
+	return domain.NewMoneyFromInstrumentCode(totalAmount, m.CurrencyCode)
 }
 
 // protoEntryToDomain converts a proto TransactionLogEntry to domain.

services/position-keeping/service/initiate_validation_test.go

@@ -388,6 +388,74 @@ func TestWithAccountValidator_Option(t *testing.T) {
 	})
 }
 
+func TestInitiateFinancialPositionLog_NonCurrencyInstrumentCodes(t *testing.T) {
+	instruments := []struct {
+		code  string
+		units int64
+		nanos int32
+		desc  string
+	}{
+		{"KWH", 8, 540000000, "energy meter read"},
+		{"CO2", 50, 0, "carbon credit purchase"},
+		{"GPU", 3, 750000000, "compute allocation"},
+		{"GAS", 1, 250000000, "gas meter read"},
+	}
+
+	for _, inst := range instruments {
+		t.Run(inst.code, func(t *testing.T) {
+			ctx := context.Background()
+			mockRepo := new(MockRepository)
+			mockEventPublisher := domain.NewInMemoryEventPublisher()
+			mockIdempotency := new(MockIdempotencyService)
+			mockMeasurementRepo := new(MockMeasurementRepository)
+
+			svc, err := service.NewPositionKeepingService(
+				mockRepo,
+				mockMeasurementRepo,
+				mockEventPublisher,
+				mockIdempotency,
+				newTestOutboxPublisher(t),
+			)
+			require.NoError(t, err)
+
+			accountID := inst.code + "-account-001"
+			req := &positionkeepingv1.InitiateFinancialPositionLogRequest{
+				AccountId: accountID,
+				InitialEntry: &positionkeepingv1.TransactionLogEntry{
+					EntryId:       uuid.NewString(),
+					TransactionId: uuid.NewString(),
+					AccountId:     accountID,
+					Amount: &commonv1.MoneyAmount{
+						Amount: &money.Money{
+							CurrencyCode: inst.code,
+							Units:        inst.units,
+							Nanos:        inst.nanos,
+						},
+					},
+					Direction:   commonv1.PostingDirection_POSTING_DIRECTION_CREDIT,
+					Description: inst.desc,
+				},
+			}
+
+			mockRepo.On("CreateWithOutbox", ctx, mock.AnythingOfType("*domain.FinancialPositionLog")).Return(nil)
+
+			resp, err := svc.InitiateFinancialPositionLog(ctx, req)
+
+			require.NoError(t, err, "instrument %s should be accepted", inst.code)
+			require.NotNil(t, resp)
+			assert.Equal(t, accountID, resp.Log.AccountId)
+
+			require.NotEmpty(t, resp.Log.TransactionLogEntries)
+			entry := resp.Log.TransactionLogEntries[0]
+			assert.Equal(t, inst.code, entry.Amount.Amount.CurrencyCode)
+			assert.Equal(t, inst.units, entry.Amount.Amount.Units)
+			assert.Equal(t, inst.nanos, entry.Amount.Amount.Nanos)
+
+			mockRepo.AssertExpectations(t)
+		})
+	}
+}
+
 func TestWithAccountValidationEnabled_Option(t *testing.T) {
 	mockRepo := new(MockRepository)
 	mockEventPublisher := domain.NewInMemoryEventPublisher()