feat: rewrite financial-accounting adapters and PostingService for asset-agnostic amounts (#2117)

* feat: rewrite financial-accounting adapters and PostingService for asset-agnostic amounts

- Add InstrumentAmountConverter with InstrumentResolver dependency for
  proper instrument metadata resolution (dimension, precision) from
  Reference Data, with fallback to legacy ParseCurrency
- Export ToProtoInstrumentAmount for use by other packages
- Redesign DepositEvent from cent-based (AmountCents int64, Currency)
  to decimal string-based (Amount string, InstrumentCode string) for
  asset-agnostic support (KWH, TONNE_CO2E, GPU_HOUR, etc.)
- Add InstrumentResolver to PostingService and PostingServiceConfig
- Rewrite buildDepositPostings to use resolveInstrument() which tries
  InstrumentResolver first, falls back to legacy currency lookup
- Update deposit consumer to convert proto AmountCents to decimal string
- Add RecordPostingAmountFloat for asset-agnostic metrics
- Remove decimalFromCents (no longer needed)

* fix: address review feedback on asset-agnostic posting layer

- Fix critical: deposit consumer no longer divides by 100; passes raw
  AmountMinorUnit to PostingService which converts using resolved
  instrument precision (e.g., /1000 for 3dp KWH, /1 for 0dp JPY)
- Fix major: use separate Prometheus counter (posting_amount_major_total)
  for float-based major-unit amounts to avoid mixing with legacy cents counter
- Fix major: tighten InstrumentAmountConverter fallback - when resolver
  is configured but fails, only fall back to ParseCurrency for known
  ISO 4217 codes; unknown instrument codes now error instead of
  silently inferring precision
- Add DepositEvent.AmountMinorUnit field for proto consumer path
  (mutually exclusive with Amount string for direct callers)
- Pass resolved amount to metrics instead of raw event data
- Add tests for minor-unit conversion (KWH 3dp, JPY 0dp)
- Add test for rejection of unknown non-currency instruments

---------

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

Author: bjcoombs

services/financial-accounting/adapters/messaging/deposit_consumer.go

@@ -9,6 +9,7 @@ import (
 
 	"buf.build/go/protovalidate"
 	"github.com/google/uuid"
+
 	eventsv1 "github.com/meridianhub/meridian/api/proto/meridian/events/v1"
 	"github.com/meridianhub/meridian/services/financial-accounting/service"
 	"github.com/meridianhub/meridian/shared/pkg/idempotency"
@@ -217,12 +218,16 @@ func (dc *DepositConsumer) processAndStoreResult(ctx context.Context, event *eve
 		return fmt.Errorf("%w: %v", ErrInvalidCurrency, event.InstrumentCode)
 	}
 
+	// Pass the raw minor-unit value as a string. The PostingService will
+	// resolve instrument precision and convert from minor to major units.
+	// This avoids hardcoding a /100 divisor that would be wrong for
+	// non-2dp instruments (e.g., JPY=0dp, KWH=3dp).
 	depositEvent := service.DepositEvent{
-		AccountID:     event.AccountId,
-		AmountCents:   event.AmountCents,
-		Currency:      currencyCode,
-		CorrelationID: event.CorrelationId,
-		ValueDate:     event.ValueDate.AsTime(),
+		AccountID:       event.AccountId,
+		AmountMinorUnit: event.AmountCents,
+		InstrumentCode:  currencyCode,
+		CorrelationID:   event.CorrelationId,
+		ValueDate:       event.ValueDate.AsTime(),
 	}
 
 	if err := dc.postingService.ProcessDeposit(ctx, depositEvent); err != nil {

services/financial-accounting/observability/metrics.go

@@ -84,6 +84,14 @@ var (
 		[]string{"direction", "currency"},
 	)
 
+	postingAmountMajorTotal = promauto.NewCounterVec(
+		prometheus.CounterOpts{
+			Name: "financial_accounting_posting_amount_major_total",
+			Help: "Total amount posted in major instrument units by instrument and direction",
+		},
+		[]string{"direction", "instrument"},
+	)
+
 	// Booking log metrics
 	bookingLogsTotal = promauto.NewCounterVec(
 		prometheus.CounterOpts{
@@ -237,6 +245,13 @@ func RecordPostingAmount(direction, currency string, amountCents int64) {
 	postingAmountTotal.WithLabelValues(direction, currency).Add(float64(amountCents))
 }
 
+// RecordPostingAmountFloat records the amount of a posting in major units for tracking total volume.
+// This uses a separate counter from RecordPostingAmount (which tracks minor units/cents)
+// to avoid mixing units in the same metric series.
+func RecordPostingAmountFloat(direction, instrumentCode string, amount float64) {
+	postingAmountMajorTotal.WithLabelValues(direction, instrumentCode).Add(amount)
+}
+
 // RecordBookingLog records a booking log creation with status.
 func RecordBookingLog(status string) {
 	bookingLogsTotal.WithLabelValues(status).Inc()

services/financial-accounting/service/adapters.go

@@ -1,6 +1,7 @@
 package service
 
 import (
+	"context"
 	"errors"
 	"fmt"
 
@@ -12,6 +13,7 @@ import (
 	financialaccountingv1 "github.com/meridianhub/meridian/api/proto/meridian/financial_accounting/v1"
 	quantityv1 "github.com/meridianhub/meridian/api/proto/meridian/quantity/v1"
 	"github.com/meridianhub/meridian/services/financial-accounting/domain"
+	"github.com/meridianhub/meridian/shared/pkg/refdata"
 )
 
 var (
@@ -21,8 +23,67 @@ var (
 
 	// ErrNilInstrumentAmount is returned when proto InstrumentAmount is nil
 	ErrNilInstrumentAmount = errors.New("instrument amount cannot be nil")
+
+	// ErrEmptyInstrumentCode is returned when the instrument code is empty
+	ErrEmptyInstrumentCode = errors.New("instrument code cannot be empty")
 )
 
+// InstrumentAmountConverter converts between proto InstrumentAmount and domain Money
+// using an InstrumentResolver for proper instrument metadata lookup.
+type InstrumentAmountConverter struct {
+	resolver refdata.InstrumentResolver
+}
+
+// NewInstrumentAmountConverter creates a converter with the given resolver.
+// If resolver is nil, conversions fall back to legacy currency-based resolution.
+func NewInstrumentAmountConverter(resolver refdata.InstrumentResolver) *InstrumentAmountConverter {
+	return &InstrumentAmountConverter{resolver: resolver}
+}
+
+// FromProto converts protobuf InstrumentAmount to domain Money using the InstrumentResolver.
+// When a resolver is configured, it is the primary path. Legacy ParseCurrency fallback
+// only applies when the resolver is nil (not configured) or for known ISO 4217 currencies
+// when the resolver returns ErrUnknownInstrument.
+func (c *InstrumentAmountConverter) FromProto(ctx context.Context, ia *quantityv1.InstrumentAmount) (domain.Money, error) {
+	if ia == nil {
+		return domain.Money{}, ErrNilInstrumentAmount
+	}
+	if ia.InstrumentCode == "" {
+		return domain.Money{}, ErrEmptyInstrumentCode
+	}
+
+	amount, err := decimal.NewFromString(ia.Amount)
+	if err != nil {
+		return domain.Money{}, fmt.Errorf("invalid amount: %w", err)
+	}
+
+	// Try resolver first for proper instrument metadata
+	if c.resolver != nil {
+		props, resolveErr := c.resolver.Resolve(ctx, ia.InstrumentCode)
+		if resolveErr == nil {
+			inst, instErr := domain.NewInstrument(props.Code, uint32(ia.Version), props.Dimension, props.Precision)
+			if instErr == nil {
+				return domain.NewMoney(amount, inst), nil
+			}
+			return domain.Money{}, fmt.Errorf("invalid instrument metadata for %q: %w", ia.InstrumentCode, instErr)
+		}
+		// Only fall back to legacy for known currencies; non-currency codes must
+		// come from the resolver to avoid silently guessed precision.
+		if _, currErr := domain.ParseCurrency(ia.InstrumentCode); currErr != nil {
+			return domain.Money{}, fmt.Errorf("failed to resolve instrument %q: %w", ia.InstrumentCode, resolveErr)
+		}
+	}
+
+	// Legacy fallback: resolver is nil or code is a known ISO 4217 currency
+	return fromProtoInstrumentAmount(ia)
+}
+
+// ToProtoInstrumentAmount converts domain Money to protobuf InstrumentAmount.
+// Preserves full decimal precision via string representation.
+func ToProtoInstrumentAmount(m domain.Money) *quantityv1.InstrumentAmount {
+	return toProtoInstrumentAmount(m)
+}
+
 // parseUUID parses and validates a UUID string.
 //
 // Returns ErrEmptyUUID if the string is empty.

services/financial-accounting/service/adapters_test.go

@@ -1,6 +1,7 @@
 package service
 
 import (
+	"context"
 	"testing"
 	"time"
 
@@ -12,6 +13,7 @@ import (
 	commonv1 "github.com/meridianhub/meridian/api/proto/meridian/common/v1"
 	quantityv1 "github.com/meridianhub/meridian/api/proto/meridian/quantity/v1"
 	"github.com/meridianhub/meridian/services/financial-accounting/domain"
+	"github.com/meridianhub/meridian/shared/pkg/refdata"
 )
 
 func TestFromProtoPostingDirection(t *testing.T) {
@@ -259,3 +261,168 @@ func TestParseUUID_Invalid(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "invalid UUID format")
 }
+
+// =============================================================================
+// InstrumentAmountConverter tests
+// =============================================================================
+
+// adapterMockInstrumentResolver implements refdata.InstrumentResolver for testing.
+type adapterMockInstrumentResolver struct {
+	instruments map[string]refdata.InstrumentProperties
+	err         error
+}
+
+func (m *adapterMockInstrumentResolver) Resolve(_ context.Context, code string) (refdata.InstrumentProperties, error) {
+	if m.err != nil {
+		return refdata.InstrumentProperties{}, m.err
+	}
+	if props, ok := m.instruments[code]; ok {
+		return props, nil
+	}
+	return refdata.InstrumentProperties{}, refdata.ErrUnknownInstrument
+}
+
+func TestInstrumentAmountConverter_FromProto_WithResolver(t *testing.T) {
+	resolver := &adapterMockInstrumentResolver{
+		instruments: map[string]refdata.InstrumentProperties{
+			"GBP":        {Code: "GBP", Dimension: "CURRENCY", Precision: 2, RoundingMode: "HALF_EVEN"},
+			"KWH":        {Code: "KWH", Dimension: "ENERGY", Precision: 3, RoundingMode: "HALF_UP"},
+			"TONNE_CO2E": {Code: "TONNE_CO2E", Dimension: "CARBON", Precision: 6, RoundingMode: "HALF_EVEN"},
+			"GPU_HOUR":   {Code: "GPU_HOUR", Dimension: "COMPUTE", Precision: 4, RoundingMode: "HALF_EVEN"},
+		},
+	}
+	converter := NewInstrumentAmountConverter(resolver)
+	ctx := context.Background()
+
+	tests := []struct {
+		name           string
+		instrumentCode string
+		amount         string
+		wantCode       string
+		wantDimension  string
+		wantPrecision  int
+	}{
+		{"GBP currency", "GBP", "100.50", "GBP", "CURRENCY", 2},
+		{"KWH energy", "KWH", "123.456", "KWH", "ENERGY", 3},
+		{"TONNE_CO2E carbon", "TONNE_CO2E", "0.001234", "TONNE_CO2E", "CARBON", 6},
+		{"GPU_HOUR compute", "GPU_HOUR", "24.5000", "GPU_HOUR", "COMPUTE", 4},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			ia := &quantityv1.InstrumentAmount{
+				Amount:         tt.amount,
+				InstrumentCode: tt.instrumentCode,
+				Version:        1,
+			}
+
+			result, err := converter.FromProto(ctx, ia)
+			require.NoError(t, err)
+			assert.Equal(t, tt.wantCode, result.Instrument.Code)
+			assert.Equal(t, tt.wantDimension, result.Instrument.Dimension)
+			assert.Equal(t, tt.wantPrecision, result.Instrument.Precision)
+		})
+	}
+}
+
+func TestInstrumentAmountConverter_FromProto_NilInput(t *testing.T) {
+	converter := NewInstrumentAmountConverter(nil)
+	_, err := converter.FromProto(context.Background(), nil)
+	require.ErrorIs(t, err, ErrNilInstrumentAmount)
+}
+
+func TestInstrumentAmountConverter_FromProto_EmptyInstrumentCode(t *testing.T) {
+	converter := NewInstrumentAmountConverter(nil)
+	ia := &quantityv1.InstrumentAmount{Amount: "100", InstrumentCode: ""}
+	_, err := converter.FromProto(context.Background(), ia)
+	require.ErrorIs(t, err, ErrEmptyInstrumentCode)
+}
+
+func TestInstrumentAmountConverter_FromProto_InvalidAmount(t *testing.T) {
+	converter := NewInstrumentAmountConverter(nil)
+	ia := &quantityv1.InstrumentAmount{Amount: "not-a-number", InstrumentCode: "GBP"}
+	_, err := converter.FromProto(context.Background(), ia)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "invalid amount")
+}
+
+func TestInstrumentAmountConverter_FromProto_FallbackToLegacy(t *testing.T) {
+	// Resolver returns error - should fall back to ParseCurrency for GBP
+	resolver := &adapterMockInstrumentResolver{err: refdata.ErrUnknownInstrument}
+	converter := NewInstrumentAmountConverter(resolver)
+
+	ia := &quantityv1.InstrumentAmount{
+		Amount:         "100.00",
+		InstrumentCode: "GBP",
+		Version:        1,
+	}
+
+	result, err := converter.FromProto(context.Background(), ia)
+	require.NoError(t, err)
+	assert.Equal(t, "GBP", result.Instrument.Code)
+	assert.Equal(t, "100", result.Amount.String())
+}
+
+func TestInstrumentAmountConverter_FromProto_NilResolver(t *testing.T) {
+	// No resolver - should use legacy fromProtoInstrumentAmount
+	converter := NewInstrumentAmountConverter(nil)
+
+	ia := &quantityv1.InstrumentAmount{
+		Amount:         "50.25",
+		InstrumentCode: "USD",
+		Version:        1,
+	}
+
+	result, err := converter.FromProto(context.Background(), ia)
+	require.NoError(t, err)
+	assert.Equal(t, "USD", result.Instrument.Code)
+	assert.Equal(t, "50.25", result.Amount.String())
+}
+
+func TestInstrumentAmountConverter_Roundtrip(t *testing.T) {
+	resolver := &adapterMockInstrumentResolver{
+		instruments: map[string]refdata.InstrumentProperties{
+			"KWH": {Code: "KWH", Dimension: "ENERGY", Precision: 3, RoundingMode: "HALF_UP"},
+		},
+	}
+	converter := NewInstrumentAmountConverter(resolver)
+
+	ia := &quantityv1.InstrumentAmount{
+		Amount:         "123.456",
+		InstrumentCode: "KWH",
+		Version:        1,
+	}
+
+	money, err := converter.FromProto(context.Background(), ia)
+	require.NoError(t, err)
+
+	roundtripped := ToProtoInstrumentAmount(money)
+	assert.Equal(t, "123.456", roundtripped.Amount)
+	assert.Equal(t, "KWH", roundtripped.InstrumentCode)
+}
+
+func TestInstrumentAmountConverter_FromProto_RejectsUnknownNonCurrency(t *testing.T) {
+	// Resolver is configured but doesn't know "UNKNOWN_ASSET". Since it's not
+	// a known ISO 4217 currency, it should error rather than infer precision.
+	resolver := &adapterMockInstrumentResolver{err: refdata.ErrUnknownInstrument}
+	converter := NewInstrumentAmountConverter(resolver)
+
+	ia := &quantityv1.InstrumentAmount{
+		Amount:         "100.00",
+		InstrumentCode: "UNKNOWN_ASSET",
+		Version:        1,
+	}
+
+	_, err := converter.FromProto(context.Background(), ia)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "failed to resolve instrument")
+}
+
+func TestToProtoInstrumentAmount_Exported(t *testing.T) {
+	inst := domain.MustCurrencyToInstrument(domain.CurrencyGBP)
+	m := domain.NewMoney(decimal.NewFromInt(42), inst)
+
+	result := ToProtoInstrumentAmount(m)
+	assert.Equal(t, "GBP", result.InstrumentCode)
+	assert.Equal(t, "42", result.Amount)
+}