components:
  schemas:
    LedgerAccountBalance:
      description: Canonical ledger account balance. Current and historical modes have distinct field-presence semantics.
      oneOf:
        - $ref: ./balance.yaml#/components/schemas/CurrentLedgerAccountBalance
        - $ref: ./balance.yaml#/components/schemas/HistoricalLedgerAccountBalance

    CurrentLedgerAccountBalance:
      description: Current materialized ledger account balance.
      type: object
      additionalProperties: false
      required:
        - ledgerAccountRef
        - balance
        - version
        - lastUpdated
      properties:
        ledgerAccountRef:
          description: Ledger account reference.
          $ref: ../objectid.yaml#/components/schemas/ObjectId
        balance:
          $ref: ../common/money.yaml#/components/schemas/Money
        version:
          description: Materialized account-balance version.
          type: integer
          format: int64
        lastUpdated:
          description: Materialized balance update timestamp.
          type: string
          format: date-time

    HistoricalLedgerAccountBalance:
      description: |
        Event-time accounting balance reconstructed from posted statement-entry deltas
        where `eventTime <= asOf`. This is not a materialized historical snapshot.
      type: object
      additionalProperties: false
      required:
        - ledgerAccountRef
        - balance
        - asOf
      properties:
        ledgerAccountRef:
          description: Ledger account reference.
          $ref: ../objectid.yaml#/components/schemas/ObjectId
        balance:
          $ref: ../common/money.yaml#/components/schemas/Money
        asOf:
          description: Canonical UTC RFC3339 event-time cutoff used for reconstruction.
          type: string
          format: date-time
          example: '2026-04-23T12:30:00Z'